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About This Manual 


Preface 


Read This First 


Code Composer Studio speeds and enhances the development process for 
programmers who create and test real-time, embedded signal processing 
applications. Code Composer Studio extends the capabilities of the Code 
Composer Integrated Development Environment (IDE) to include full 
awareness of the DSP target by the host and real-time analysis tools. 


This tutorial assumes that you have Code Composer Studio, which includes 
the TMS320C54x code generation tools along with the APIs and plug-ins for 
both DSP/BIOS and RTDX. This manual also assumes that you have 
installed a target board in your PC containing the DSP device. 


If you only have Code Composer Studio Simulator and the code generation 
tools, but not the complete Code Composer Studio, you can perform the 
steps in Chapter 2 and Chapter 4. 


If you are using the DSP simulator instead of a board, you are also limited to 
performing the steps in Chapter 2 and Chapter 4. 


This tutorial introduces you to some of the key features of Code Composer 
Studio. The intention is not to provide an exhaustive description of every 
feature. Instead, the objective is to prepare you to begin DSP development 
with Code Composer Studio. 


Notational Conventions 


Notational Conventions 


This document uses the following conventions: 


a 
a 


The TMS320C54x core is also referred to as ’C54x. 


Program listings, program examples, and interactive displays are shown 
ina special typeface. Examples use a bold version of the special 
typeface for emphasis; interactive displays use a bold version of the 
special typeface to distinguish commands that you enter from items that 
the system displays (such as prompts, command output, error messages, 
etc.). 


Here is a sample program listing: 


Void copy(HST_Obj *input, HST_Obj *output) 
{ 


PIP_Obj <1, Outs 
Uns eave, *dsty 
Uns size; 


In syntax descriptions, the instruction, command, or directive is in a bold 
typeface and parameters are in an italic typeface. Portions of a syntax 
that are in bold should be entered as shown; portions of a syntax that are 
in italics describe the type of information that should be entered. Syntax 
that is entered on a command line is centered. Syntax that is used in a 
text file is left-justified. 


Square brackets ( [ ] ) identify an optional parameter. If you use an 
optional parameter, you specify the information within the brackets. 
Unless the square brackets are in a bold typeface, do not enter the 
brackets themselves. 


Related Documentation from Texas Instruments 


Related Documentation from Texas Instruments 


The following books describe the devices, related support tools, and Code 
Composer Studio. 


Most of these documents are available in Adobe Acrobat format after you 
install Code Composer Studio. To open a document, from the Windows Start 
menu, choose Programs—>Code Composer Studio 'C5400—>Documentation. 


To obtain a printed copy of any of these documents, call the Texas 
Instruments Literature Response Center at (800) 477-8924. When ordering, 
please identify the book by its title and literature number. 


Code Composer Studio User’s Guide (literature number SPRU328) 
explains how to use the Code Composer Studio development environment 
to build and debug embedded real-time DSP applications. 


TMS320C54x DSP/BIOS User's Guide (literature number SPRU326) 
describes how to use DSP/BIOS tools and APIs to analyze embedded 
real-time DSP applications. 


TMS320C54x Assembly Language Tools User's Guide (literature number 
SPRU102) describes the assembly language tools (assembler, linker, 
and other tools used to develop assembly language code), assembler 
directives, macros, common object file format, and symbolic debugging 
directives for the °C54x generation of devices. 


TMS320C54x Optimizing C Compiler User's Guide (literature number 
SPRU103) describes the ’C54x C compiler and the assembly optimizer. 
This C compiler accepts ANSI standard C source code and produces 
assembly language source code for the ’C54x generation of devices. 
The assembly optimizer helps you optimize your assembly code. 


TMS320C5x User's Guide (literature number SPRU056) describes the 'C5x 
16-bit, fixed-point, general-purpose digital signal processors. Covered 
are its architecture, internal register structure, instruction set, pipeline, 
specifications, DMA, I/O ports, and on-chip peripherals. 


TMS320C54x DSP Reference Set is composed of four volumes that can be 
ordered as a set with literature number SPRU210. To order an individual 
book, use the document-specific literature number: 


TMS320C54x DSP Reference Set, Volume 1: CPU and Peripherals 
(literature number SPRU131) describes the TMS320C54x 16-bit, 
fixed-point, general-purpose digital signal processors. Covered are its 
architecture, internal register structure, data and program addressing, 
the instruction pipeline, and on-chip peripherals. Also includes 
development support information, parts lists, and design considerations 
for using the XDS510 emulator. 
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Related Documentation 


TMS320C54x DSP Reference Set, Volume 2: Mnemonic Instruction Set 
(literature number SPRU172) describes the TMS320C54x digital signal 
processor mnemonic instructions individually. Also includes a summary 
of instruction set classes and cycles. 


TMS320C54x DSP Reference Set, Volume 3: Algebraic Instruction Set 
(literature number SPRU179) describes the TMS320C54x digital signal 
processor algebraic instructions individually. Also includes a summary of 
instruction set classes and cycles. 


TMS320C54x DSP Reference Set, Volume 4: Applications Guide 
(literature number SPRU173) describes software and hardware 
applications for the TMS320C54x digital signal processor. Also includes 
development support information, parts lists, and design considerations 
for using the XDS510 emulator. 


TMS320 DSP Designer's Notebook: Volume 17 (literature number 
SPRT125) presents solutions to common design problems using 'C2x, 
'C3x, 'C4x, 'C5x, and other TI DSPs. 


Related Documentation 


Trademarks 


vi 


You can use the following books to supplement this user's guide: 


American National Standard for Information Systems-Programming 
Language C X3.159-1989, American National Standards Institute. 


The C Programming Language (second edition), by Brian W. Kernighan 
and Dennis M. Ritchie. Prentice Hall Press, 1988. 


Programming in ANSI C, Kochan, Steve G. Sams Publishing, 1994. 


C: A Reference Manual, Harbison, Samuel and Guy Steele. Prentice Hall 
Computer Books, 1994. 


MS-DOS, Windows, and Windows NT are trademarks of Microsoft 
Corporation. Other Microsoft products referenced herein are either 
trademarks or registered trademarks of Microsoft. 


The Texas Instruments logo and Texas Instruments are registered 
trademarks of Texas Instruments. Trademarks of Texas Instruments include: 
Tl, XDS, Code Composer Studio, Probe Point, Code Explorer, DSP/BIOS, 
RTDX, Online DSP Lab, BlOSuite, and SPOX. 


All other brand or product names are trademarks or registered trademarks of 
their respective companies or organizations. 
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Chapter 1 


Code Composer Studio Overview 


This chapter provides an overview of the Code Composer Studio software 
development process, the components of Code Composer Studio, and the 
files and variables used by Code Composer Studio. 


Code Composer Studio speeds and enhances the development process for 
programmers who create and test real-time, embedded signal processing 
applications. It provides tools for configuring, building, debugging, tracing, 
and analyzing programs. 


Topic Page 
1.1 Code Composer Studio Development...............+.+2++005 h-2 
1.2 Code Generation Tools.............0 0c cece eee eens 1-4) 
1.3 Code Composer Studio Integrated Development Environment .. . -6 
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1.1 


Code Composer Studio Development 


Code Composer Studio extends the basic code generation tools with a set of 
debugging and real-time analysis capabilities. Code Composer Studio 
supports all phases of the development cycle shown here: 


Design 


conceptual 
planning 


b> 


Code & build 
create project, 
write source code, 
configuration file 


Debug 
syntax checking, 
probe points, 
logging, etc. 


Analyze 
real-time 
debugging, 
statistics, tracing 


| 


| 


In order to use this tutorial, you should have already done the following: 


a) 


Install target board and driver software. Follow the installation 
instructions provided with the board. If you are using the simulator or a 
target board whose driver software is provided with this product you can 
perform the steps in the Installation Guide for this product. 


Install Code Composer Studio. Follow the installation instructions. If you 
have Code Composer Studio Simulator and the TMS320C54x code 
generation tools, but not the full Code Composer Studio, you can perform 


the steps in Chapter 2 and in Chapter 4. 


Run Code Composer Studio Setup. The setup program allows Code 


Composer Studio to use the drivers installed for the target board. 


Code Composer Studio Development 


Code Composer Studio includes the following components: 
L) TMS320C54x code generation tools: see section 1.2 


1 Code Composer Studio Integrated Development Environment (IDE): see 
section 1.3 


14 DSP/BIOS plug-ins and API: see section 1.4 
LY RTDX plug-in, host interface, and API: see section 1.5 


These components work together as shown here: 


Target 


O0000000 
fe} 


Code Composer Studio 


oO 

=< Oo 
—w (e} (o} 
(eo) (o) 
oO [e} 
‘ ; Code Composer editor ° ° 
Configuration p 8 . 
Tool : x 6 
source files | .¢ . : COO000006 


.cdb 


(Config 
database) DSP/BIOS API 


Code 


generalion 
cfg.cmd : tools 
ay 254 Code Composer project 

ctg.h54 Compiler, 


assembler, 
Inker... 


OLE 
application RTDX |JDSP/BIOS |) 3rd part 
using RTDX plug-ins lacie executable 


Code Composer debugger 


G 
Host emulation support Target hardware 
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1.2 Code Generation Tools 


The code generation tools provide the foundation for the development 
environment provided by Code Composer Studio. Figure 1-1 shows a typical 
software development flow. The most common software development path for 
C language programs is shaded. Other portions are peripheral functions that 
enhance the development process. 


Figure 1-1 Software Development Flow 
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Code Generation Tools 


The following list describes the tools shown in Figure 1-1: 


| 


The C compiler accepts C source code and produces assembly 
language source code. See the TMS320C54x Optimizing C Compiler 
User's Guide for details. 


The assembler translates assembly language source files into machine 
language object files. The machine language is based on common object 
file format (COFF). See the TMS320C54x Assembly Language Tools 
User's Guide for details. 


The linker combines object files into a single executable object module. 
As it creates the executable module, it performs relocation and resolves 
external references. The linker accepts relocatable COFF object files and 
object libraries as input. See the TMS320C54x Optimizing C Compiler 
User's Guide and the TMS320C54x Assembly Language Tools User's 
Guide for details. 


The archiver allows you to collect a group of files into a single archive 
file, called a library. The archiver also allows you to modify a library by 
deleting, replacing, extracting, or adding members. See _ the 
TMS320C54x Assembly Language Tools User’s Guide for details. 


The mnemonic-to-algebraic assembly translator utility converts an 
assembly language source file containing mnemonic instructions into an 
assembly language source file containing algebraic instructions. See the 
TMS320C54x Assembly Language Tools User’s Guide for details. 


You can use the library-build utility to build your own customized 
run-time-support library. See the TMS320C54x Optimizing C Compiler 
User's Guide for details. 


The run-time-support libraries contain ANSI standard run-time-support 
functions, compiler-utility functions, floating-point arithmetic functions, 
and I/O functions that are supported by the C compiler. See the 
TMS320C54x Optimizing C Compiler User’s Guide for details. 


The hex conversion utility converts a COFF object file into Tl-Tagged, 
ASCll-hex, Intel, Motorola-S, or Tektronix object format. You can 
download the converted file to an EPROM programmer. See the 
TMS320C54x Assembly Language Tools User’s Guide for details. 


The cross-reference lister uses object files to produce a 
cross-reference listing showing symbols, their definitions, and their 
references in the linked source files. See the TMS320C54x Assembly 
Language Tools User's Guide for details. 


The absolute lister accepts linked object files as input and creates .abs 
files as output. You assemble the .abs files to produce a listing that 
contains absolute addresses rather than relative addresses. Without the 
absolute lister, producing such a listing would be tedious and require 
many manual operations. 
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Code Composer Studio Integrated Development Environment 


1.3 Code Composer Studio Integrated Development Environment 


The Code Composer Studio Integrated Development Environment (IDE) is 
designed to allow you to edit, build, and debug DSP target programs. 


1.3.1. Program Code Editing Features 


Code Composer Studio allows you to edit C and assembly source code. You 
can also view C source code with the corresponding assembly instructions 
shown after the C statements. 


be Hello.c lel Es 


/* write a string to stdout */ | 
puts("hello world!\n"); 
0000:1402 F274 CALLD puts 


0000:1404 FoO20 LD #640h,0,A 


#ifdef FILEIO 

“* clear char arrays */ 
for {1 = 0; 1 < BUFSIZE; i++) f{ 
Be Soe oT 


0000:1406 7604 3 #0h,4h 
0000:1408 F7B8 SSBX SXM , 
0000:1409 ES1E LD #leh,A 
0000:140A4 0804 SUB 4h A 
0000:140B F847 BC L3,ALEQ 
0000:141F 6604 ADDM 1h,4h 
0000:1421 F7B6 SSBX SXM 
0000:1422 E61E LD #leh,A 
0000:1423 0804 SUB 4h 3 
0000:1424 F846 BC L2,AGT 
scanstr[i] = 0; 
0000:140D 4818 LDM SPA Fi 
Li LP, 


The integrated editor provides support for the following activities: 
LY Highlighting of keywords, comments, and strings in color 


[1 Marking C blocks in parentheses and braces, finding matching or next 
parenthesis or brace 


1) Increasing and decreasing indentation level, customizable tab stops 


L) Finding and replacing in one or more files, find next and previous, quick 
search 


1) Undoing and redoing multiple actions 


ul 


Getting context-sensitive help 


14 Customizing keyboard command assignments 


Code Composer Studio Integrated Development Environment 


1.3.2 Application Building Features 


Within Code Composer Studio, you create 
an application by adding files to a project. 
The project file is used to build the 


Pie eer : i cS Project 

application. Files in a project can include = a HELLO.MAK 
C source files, assembly source files, DSP/BIOS Config 
object files, libraries, linker command files, HELLO.CMD 
and include files. -Gqj Include 
You can use a window to specify the i HELLO.H 
options you want to use when compiling, a (4 Libraries 
assembling, and linking a project. = Source 

HELLO.C 
Using a project, Code Composer Studio VECTORS.ASM 


can create a full build or an incremental 
build and can compile individual files. It 
can also scan files to build an include file 
dependency tree for the entire project. 


Code Composer Studio’s build facilities can be used as an alternative to 
traditional makefiles. If you want to continue using traditional makefiles for 
your project, Code Composer Studio also permits that. 


1.3.3. Application Debugging Features 


Code Composer Studio provides support for the following debugging 
activities: 


Setting breakpoints with a number of stepping options 
Automatically updating windows at breakpoints 
Watching variables 

Viewing and editing memory and registers 


Viewing the call stack 


Uovovoevo vu 


Using Probe Point tools to stream data to and from the target and to 
gather memory snapshots 


LY Graphing signals on the target 


L) Profiling execution statistics 


14 Viewing disassembled and C instructions executing on target 


Code Composer Studio also provides the GEL language, which allows 
developers to add functions to the Code Composer Studio menus for 
commonly performed tasks. 
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DSP/BIOS Plug-ins 


1.4 


Oecd | ET ee 
Other Threads 


PRD Ticks 


Time 
Assettions 


1.4.1 


DSP/BIOS Plug-ins 


During the analysis phase of the software development cycle, traditional 
debugging features are ineffective for diagnosing subtle problems that arise 
from time-dependent interactions. 


The Code Composer Studio plug-ins provided with DSP/BIOS support such 
real-time analysis. You can use them to visually probe, trace, and monitor a 
DSP application with minimal impact on real-time performance. For example, 
the Execution Graph shown below displays the sequence in which various 
program threads execute. (Threads is a general term used to refer to any 
thread of execution, e.g., a hardware ISR, a software interrupt, an idle 
function, or a periodic function.) 


waiting 
OO ready 
© unknown 
i error 

i running 


go TOs CS DN Ts FSS SE Fee nF Fl ee Oe Oe OO NO CO BO CO Ae On A COD FON Day 
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The DSP/BIOS API provides the following real-time analysis capabilities: 


11 Program tracing. Displaying events written to target logs and reflecting 
dynamic control flow during program execution 


1) Performance monitoring. Tracking statistics that reflect the use of target 
resources, such as processor loading and thread timing 


1 File streaming. Binding target-resident I/O objects to host files 


DSP/BIOS also provides a priority-based scheduler that you can choose to 
use in your applications. This scheduler supports periodic execution of 
functions and multi-priority threading. 


DSP/BIOS Configuration 


You can create configuration files in the Code Composer Studio environment 
that define objects used by the DSP/BIOS API. This file also simplifies 
memory mapping and hardware ISR vector mapping, so you may want to use 
it even if you are not using the DSP/BIOS API. 


A configuration file has two roles: 


LY It lets you set global run-time parameters. 


1 It serves as a visual editor for creating and setting properties for run-time 
objects that are used by the target application’s DSP/BIOS API calls. 
These objects include software interrupts, I/O pipes, and event logs. 


DSP/BIOS Plug-ins 


When you open a configuration file in Code Composer Studio, a window like 
the following one appears. 


re hello.cdb [fol x] 


Estimated Data Size: 1526 Est. Min. Stack Size{ PRD_clock properties 


Project Manager 
@ Global Settings 
£0 CLK - Clock Manager 

£t PRD_clock 
HST - Host Channel Manager 
Hw - Hardware Interrupt Service Routine 
sy) IDL - Idle Function Manager 
@ LOG - Event Log Manager 
a MEM - Memory Section Manager 
ah, PIP - Buffered Pipe Manager 
oO PRD - Periodic Function Manager 

RTD - Real-Time Data Exchange Setting 
a STS - Statistics Object Manager 

3 SWI - Software Interrupt Manager 


This clock function... 
PRD_F_tick 


function 


+ 


+) --) 4) 


+) 


Unlike systems that create objects at run time with API calls that require extra 
target overhead (especially code space), all DSP/BIOS objects are statically 
configured and bound into an executable program image. In addition to 
minimizing the target memory footprint by eliminating run-time code and 
optimizing internal data structures, this static configuration strategy detects 
errors earlier by validating object properties before program execution. 


You can use a configuration file in both programs that use the DSP/BIOS API 
and in programs that do not. A configuration file simplifies ISR vector and 
memory section addressing for all programs. 


Saving a configuration file generates several files that you must link with your 
application. See section 1.7.2 for details about these files. 
1.4.2 DSP/BIOS API Modules 


Unlike traditional debugging, which is external to the executing program, the 
DSP/BIOS features require the target program to be linked with certain 
DSP/BIOS API modules. 


A program can use one or more DSP/BIOS modules by defining DSP/BIOS 
objects in a configuration file, declaring these objects as external, and calling 
DSP/BIOS API functions in the source code. 
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Each module has a separate C header file or assembly macro file you can 
include in your program. This allows you to minimize the program size in a 
program that uses some, but not all, DSP/BIOS modules. 


The DSP/BIOS API calls (in C and assembly) are optimized to use minimal 
resources on your target DSP. 


The DSP/BIOS API is divided into the following modules. All the API calls 
within a module begin with the letter codes shown here. 


| 


CLK. The on-chip timer module controls the on-chip timer and provides 
a logical 32-bit real-time clock with a high-resolution interrupt rate as fine 
as the resolution of the on-chip timer register (1 instruction cycle) and a 
low-resolution interrupt rate as long as several milliseconds or longer. 


HST. The host input/output module manages host channel objects, which 
allow an application to stream data between the target and the host. Host 
channels are statically configured for inout or output. 


HWI. The hardware interrupt module provides support for hardware 
interrupt routines. In a configuration file, you can assign functions that run 
when hardware interrupts occur. 


IDL. The idle function module manages idle functions, which are run ina 
loop when the target program has no higher priority functions to perform. 


LOG. The log module manages LOG objects, which capture events in 
real time while the target program executes. You can use system logs or 
define your own logs. You can view messages in these logs in real time 
with Code Composer Studio. 


MEM. The memory module allows you to specify the memory segments 
required to locate the various code and data sections of a target program. 


PIP. The data pipe module manages data pipes, which are used to buffer 
streams of input and output data. These data pipes provide a consistent 
software data structure you can use to drive I/O between the DSP device 
and other real-time peripheral devices. 


PRD. The periodic function module manages periodic objects, which 
trigger cyclic execution of program functions. The execution rate of these 
objects can be controlled by the clock rate maintained by the CLK module 
or by regular calls to PRD_tick, usually in response to hardware interrupts 
from peripherals that produce or consume streams of data. 


RTDX. Real-Time Data Exchange permits the data to be exchanged 
between the host and target in real time, and then to be analyzed and 
displayed on the host using any OLE automation client. See section 1.5 
for more information. 


DSP/BIOS Plug-ins 


1 STS. The statistics module manages statistics accumulators, which store 
key statistics while a program runs. You can view these statistics in real 
time with Code Composer Studio. 


1 SWI. The software interrupt module manages software interrupts, which 
are patterned after hardware interrupt service routines (ISRs). When a 
target program posts an SWI object with an API call, the SWI module 
schedules execution of the corresponding function. Software interrupts 
can have up to 15 priority levels; all levels are below the priority level of 
hardware ISRs. 


1 TRC. The trace module manages a set of trace control bits which control 
the real-time capture of program information through event logs and 
statistics accumulators. There are no TRC objects, so the trace module 
is not listed in configuration files. 


For details about each module, see the online help or the TMS320C54x 
DSP/BIOS User's Guide. 
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1.5 Hardware Emulation and Real-Time Data Exchange 


Tl DSPs provide on-chip emulation support that enables Code Composer 
Studio to control program execution and monitor real-time program activity. 
Communication with this on-chip emulation support occurs via an enhanced 
JTAG link. This link is a low-intrusion way of connecting into any DSP system. 
An emulator interface, like the Tl XDS510, provides the host side of the JTAG 
connection. Evaluation boards provide an on-board JTAG emulator interface 
for convenience. 

The on-chip emulation hardware provides a variety of capabilities: 

Starting, stopping, or resetting the DSP 

Loading code or data into the DSP 

Examining the registers or memory of the DSP 

Hardware instruction or data-dependent breakpoints 

A variety of counting capabilities including cycle-accurate profiling 


Real-time data exchange (RTDX) between the host and the DSP 


Uococoeco deo 


Code Composer Studio provides built-in support for these on-chip 
capabilities. In addition, RTDX capability is exposed through host and DSP 
APIs, allowing for bi-directional real-time communications between the host 
and DSP. 


RTDX provides real-time, continuous visibility into the way DSP applications 
operate in the real world. RTDX allows system developers to transfer data 
between a host computer and DSP devices without stopping their target 
application. The data can be analyzed and visualized on the host using any 
OLE automation client. This shortens development time by giving designers 
a realistic representation of the way their systems actually operate. 
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Hardware Emulation and Real-Time Data Exchange 


RTDX consists of both target and host components. A small RTDX software 
library runs on the target DSP The designer's DSP application makes 
function calls to this library’s API in order to pass data to or from it. This library 
uses the on-chip emulation hardware to move data to or from the host 
platform via an enhanced JTAG interface. Data transfer to the host occurs in 
real time while the DSP application is running. 


PC TMS320 DSP 


User display 


Code Composer 


RTDX host 
library 


JTAG 
TI display 


Third party 
display 


RTDX COM API RTDX target API 


Emulation 
Application 


RTDX target library 


On the host platform, an RTDX library operates in conjunction with Code 
Composer Studio. Display and analysis tools can communicate with RTDX 
via an easy-to-use COM API to obtain the target data or send data to the DSP 
application. Designers may use standard software display packages, such as 
National Instruments' LabVIEW, Quinn-Curtis' Real-Time Graphics Tools, or 
Microsoft Excel. Alternatively, designers can develop their own Visual Basic 
or Visual C++ applications. 


RTDX can also record real-time data and play it back for non-real-time 
analysis. The following sample display features National Instruments’ 
LabVIEW. On the target a raw signal pattern is run through an FIR filter, and 
both the raw and filtered signals are sent to the host via RTDX. On the host 
the LabVIEW display obtains the signal data via the RTDX COM API. These 
two signals appear on the left half of the display. To confirm that the target’s 
FIR filter is operating correctly, power spectrums are produced. The target’s 
filtered signal is run through a LabVIEW power spectrum and displayed on 
the top right. The target’s raw signal is run through a LabVIEW FIR filter 
followed by a LabVIEW power spectrum and displayed on the bottom right. 
Comparison of these two power spectrums validates the target FIR filter. 
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RTDX is well-suited for a variety of control, servo, and audio applications. For 
example, wireless telecommunications manufacturers can capture the 
outputs of their vocoder algorithms to check the implementations of speech 
applications. Embedded control systems also benefit. Hard disk drive 
designers can test their applications without crashing the drive with improper 
signals to the servo motor, and engine control designers can analyze 
changing factors like heat and environmental conditions while the control 
application is running. For all of these applications, users can select 
visualization tools that display information in a way that is most meaningful to 
them. Future Tl DSPs will enable RTDX bandwidth increases, providing 
greater system visibility to an even larger number of applications. For more 
information on RTDX, see the RTDX online help available within Code 
Composer Studio. 


1.6 Third-Party Plug-ins 
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Third-party software providers can create ActiveX plug-ins that complement 
the functionality of Code Composer Studio. A number of third-party plug-ins 
are available for a variety of purposes. 


Code Composer Studio Files and Variables 


1.7 Code Composer Studio Files and Variables 


The following sections provide an overview of the folders that contain the 
Code Composer Studio files, the types of files you use, and the environment 
variables used by Code Composer Studio. 


1.7.1 Installation Folders 


The installation process creates the subfolders shown here in the folder 
where you install Code Composer Studio (typically c:\ti). Additionally, 
subfolders are created in the Windows directory (c:\windows or c:\winnt). 


a 
Ly 


The c:\ti structure contains the following directories: Ga ti 
bin. Various utility programs (9 bin 
=| ¢5400 
c5400\bios. Files used when building programs H 7 3 hiss 
that use the DSP/BIOS API -Ga ce 
c5400\cgtools. The Texas Instruments code (Qj catools 
generation tools () docs 
)-{) examples 
c5400\examples. Code examples E-Bay td 
c5400\rtdx. Files for use with RTDX {J tutorial 
i ee BE 
c5400\tutorial. The examples you use in this ie bin 
manual a oe! 


Ly 
a 


cc\bin. Program files for the Code Composer 
Studio environment 


cc\gel. GEL files for use with Code Composer Studio 
docs. Documentation and manuals in PDF format 


myprojects. Location provided for your copies of the tutorial examples 
and your project files 


The following directory structure is added to the © & Windows 


Windows directory: BG ti 

4 ti\drivers. Files for various DSP board drivers (9) drivers 
: : . (9 plugins 

) ti\plugins. Plug-ins for use with Code Composer uninstall 
Studio 

LY ti\uninstall. Files supporting Code Composer Studio software removal 
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1.7.2 
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File Extensions 


While using Code Composer Studio, you work with files that have the following 
file-naming conventions: 


Cy 


Cy 


LU 


Uovo wu 


project.mak. Project file used by Code Composer Studio to define a 
project and build a program 


program.c. C program source file(s) 
program.asm. Assembly program source file(s) 


filename.h. Header files for C programs, including header files for 
DSP/BIOS API modules 


filename.lib. Library files 
project.cmd. Linker command files 
program.obj. Object files compiled or assembled from your source files 


program.out. An executable program for the target (fully compiled, 
assembled, and linked). You can load and run this program with Code 
Composer Studio. 


project.wks. Workspace file used by Code Composer Studio to store 
information about your environment settings 


program.cdb. Configuration database file created within Code Composer 
Studio. This file is required for applications that use the DSP/BIOS API, 
and is optional for other applications. The following files are also 
generated when you save a configuration file: 


M@ programcfg.cmd. Linker command file 
H@ programcfg.h54. Header file 
HM programcfg.s54. Assembly source file 


1.7.3 Environment Variables 


Code Composer Studio Files and Variables 


The installation procedure defines the following variables in your 
autoexec.bat file (for Windows 95 and 98) or as environment variables (for 


Windows NT): 


Table 1-1 Environment Variables 


Variable 


Description 


C54X_A_DIR 


C54X_C_DIR 


PATH 


A search list used by the assembler to find library and include 
files for DSP/BIOS, RTDX, and the code generation tools. See 
the TMS320C54x Assembly Language Tools User's Guide for 
details. 


A search list used by the compiler and linker to find library and 
include files for DSP/BIOS, RTDX, and the code generation 
tools. See the TMS320C54x Optimizing C Compiler User's 
Guide for details. 


A list of folders is added to your PATH definition. The default is to 
add the c:\ti\c5400\cgtools\bin and c:\ti\bin folders. 


1.7.4 Increasing DOS Environment Space 


If you are using Windows 95, you may need to increase your DOS shell 
environment space to support the environment variables required to build 
Code Composer Studio applications. 


Add the following line to the config.sys file and then restart your computer: 


shell=c:\windows\command.com /e:4096 /p 
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Developing a Simple Program 


This chapter introduces Code Composer Studio and shows the basic process 
used to create, build, debug, and test programs. 


In this chapter, you create and test a simple program that displays a hello 
world message. 


This tutorial introduces you to some of the key features of Code Composer 
Studio. The intention is not to provide an exhaustive description of every 
feature. Instead, the objective is to prepare you to begin DSP software 
development with Code Composer Studio. 


In order to use this tutorial, you should have already installed Code Composer 
Studio according to the installation instructions. It is recommended that you 
use Code Composer Studio with a target board rather than with the simulator. 
If you have Code Composer and the Code Generation Tools, but not Code 
Composer Studio, or if you are using the simulator, you can perform the steps 
in Chapter 2 and Chapter 4 only. 


Topic Page 
2:1) eGreatingialNew Projects ccr-rrs cresrarersickeueyaynictay teeavete ceeveuteneeetete b-d 
2.2 Adding Files to a Project ............00ccecceeeeceeeeeeeees 2-3 
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2.5 Changing Program Options and Fixing Syntax Errors .......... 2-7 
2.6 Using Breakpoints and the Watch Window.................005 2-9 
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2.8 Profiling Code Execution Time .............00eeeeeeeeeeeee 2-12 
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Creating a New Project 


2.1 Creating a New Project 


In this chapter, you create a project with Code Composer Studio and add 
source code files and libraries to the project. Your project uses standard C 
library functions to display a hello world message. 


1) If you installed Code Composer Studio in c:ti, create a folder called 
hello1 in the c:\tiimyprojects folder. (If you installed elsewhere, create a 
folder within the myprojects folder in the location where you installed.) 


2) Copy all files from the c:\tiic5400\tutorial\hello1 folder to this new folder. 


3) From the Windows Start menu, choose Programs-+Code Composer 
Studio ’'C5400-—CCStudio. (Or, double-click the Code Composer Studio 
icon on your desktop.) 


| Code Composer 
File Edit View Project Debug Profiler Option Tools Window Help 
Qa * SR oo 


= 


GEL files 
Project 


~ EY File View 
{DSP HALTED For Help, press F1 


‘Note: Code Composer Studio Setup 


If you get an error message the first time you try to start Code Composer 
Studio, make sure you ran Code Composer Setup after installing Code 
Composer Studio. If you have a target board other than the ones mentioned 
in the instructions provided with the CD-ROM, see the documentation 


provided with your target board for the correct I/O port address. 
L 


4) Choose the Project>New menu item. 


5) Inthe Save New Project As window, select the working folder you created 
and click Open. Type myhello as the filename and click Save. Code 
Composer Studio creates a project file called myhello.mak. This file 
stores your project settings and references the various files used by your 
project. 
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2.2 Adding Files to a Project 


1) 
2) 


Choose Project—Add Files to Project. Select hello.c and click Open. 


Choose Project—Add Files to Project. Select Asm Source Files (*.asm) 
in the Files of type box. Select vectors.asm and click Open. This file 
contains assembly instructions needed to set the RESET interrupt to 
branch to the program’s C entry point, c_intOO. (For more complex 
programs, you can define additional interrupt vectors in vectors.asm, or 
you can use DSP/BIOS as shown in section 3.1, page 3-2 to define all the 
interrupt vectors automatically.) 


Choose Project-Add Files to Project. Select Linker Command File 
(*.cmd) in the Files of type box. Select hello.cmd and click Open. This file 
maps sections to memory. 


Choose Project—Add Files to Project. 
Go to the compiler library folder 
(C\ti\c5400\cgtools\lib). Select Object 
and Library Files (*.o*, *.lib) in the 
Files of type box. Select rts.lib and 
click Open. This library provides 
run-time support for the target DSP. 


Files 
(9 GEL files 
oar] 
eo MYHELLO.MAK 
(9 DSP/BIOS Config 
HELLO.CMD 


(} Include 
Expand the Project list by clicking the =) Libraries 
+ signs next to Project, RTS.LIB 
MYHELLO.MAK, Libraries, = and =) Source 
Source. This list is called the Project HELLO.C 


View. VECTORS.ASM 


‘Note: Opening Project View 


If you do not see the Project View, choose View—Project. Click the File icon 
at the bottom of the Project View if the Bookmarks icon is selected. 


6) 


Notice that include files do not yet appear in your Project View. You do not 
need to manually add include files to your project, because Code 
Composer Studio finds them automatically when it scans _ for 
dependencies as part of the build process. After you build your project, 
the include files appear in the Project View. 


If you need to remove a file from the project, right click on the file in the Project 
View and choose Remove from project in the pop-up menu. 
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When building the program, Code Composer Studio finds files by searching 
for project files in the following path order: 


11 The folder that contains the source file. 


14 The folders listed in the Include Search Path for the compiler or 
assembler options (from left to right). 


L1 The folders listed in the definitions of the C54X_C_DIR (compiler) and 
C54X_A_DIR (assembler) environment variables (from left to right). The 
C54X_C_DIR environment variable defined by the installation points to 
the folder that contains the rts.lib file. 


2.3 Reviewing the Code 


1) Double-click on the HELLO.C file in the Project View. You see the source 
code in the right half of the window. 


2) You may want to make the window larger so that you can see more of the 
source code at once. You can also choose a smaller font for this window 
by choosing Option—Font. 


/* s=ss===== hello.c ======== a] 


#include <stdio.h> 
#include "hello.h" 


#define BUFSIZE 30 


struct PARMS str = 


{ 
2934, 
9432, 
213; 
9432, 
&str 
}; 


/* 
. main 
AG: 
void main() 
{ 
#ifdef FILEIO 
int i; 
char scanStr[BUFSIZE]; 
char fileStr[BUFSIZE]; 
size_t readSize; 
FILE *EPEL; 
#endif 


/* write a string to stdout */ 
puts ("hello world!\n"); 


2-4 


Building and Running the Program 


#ifdef FILEIO 
/* clear char arrays */ 
for (i = 0; i < BUFSIZE; i++) { 
scanStr[i] 0 /* deliberate syntax error */ 
fileStr[i] Os 


} 


/* vead a string from stdin */ 
scanf("%s", scanStr); 


/* open a file on the host and write char array */ 
fotr = fopen("file.txt", "w"); 

forintf(fptr, "Ss", scanStr); 

Fcolose(fptr); 


/* open a file on the host and read char array */ 


fotr = fopen("file.txt", "r"); 
Fseek(fptr, OL, SEEK_SET); 
readSize = fread(fileStr, sizeof(char), BUFSIZE, fptr); 


printf("Read a %d byte char array: %s \n", readSize, fileStr); 
Fclose(fptr); 

#endif 

} 


When FILEIO is undefined, this is a simple program that uses the standard 
puts() function to display a hello world message. When you define FILEIO (as 
you do in section 2.5, page 2-7), this program prompts for a string and prints 
it to a file. It then reads the string from the file and prints it and a message 
about its length to standard output. 


2.4 Building and Running the Program 


Code Composer Studio automatically saves changes to the project setup as 
you make them. In case you exited from Code Composer Studio after the 
previous section, you can return to the point where you stopped working by 
restarting Code Composer Studio and using Project-Open. 


‘Note: Resetting the Target DSP 


If you can start Code Composer Studio the first time, but a subsequent time 
you get an error message that says it cannot initialize the target DSP, 
choose the Debug—Reset DSP menu item. If this does not correct the 


problem, you may need to run a reset utility provided with your target board. 
[ee 


Developing a Simple Program 2-5 


Building and Running the Program 


To build and run the program, follow these steps: 


1) Choose Project>Rebuild All or click the (Rebuild All) toolbar button. 
Code Composer Studio recompiles, reassembles, and relinks all the files 
in the project. Messages about this process are shown in a frame at the 
bottom of the window. 


2) Choose File->Load Program. Select the program you just rebuilt, 
myhello.out, and click Open. (It should be in the c:\ti\imyprojects\hello1 
folder unless you installed Code Composer Studio elsewhere.) Code 
Composer Studio loads the program onto the target DSP and opens a 
Dis-Assembly window that shows the disassembled instructions that 
make up the program. (Notice that Code Composer Studio also 
automatically opens a tabbed area at the bottom of the window to show 
output the program sends to stdout.) 


3) Click on an assembly instruction in the Dis-Assembly window. (Click on 
the actual instruction, not the address of the instruction or the fields 
passed to the instruction.) Press the F1 key. Code Composer Studio 
searches for help on that instruction. This is a good way to get help on an 
unfamiliar assembly instruction. 


4) Choose Debug—Run or click the sz (Run) toolbar button. 


Note: Screen Size and Resolution 


Depending on the size and resolution of your screen, part of the toolbar 
may be hidden by the Build window. To view the entire toolbar, right-click in 


the Build window and deselect Allow Docking. 
Ll 


When you run the program, you see the hello world message in the 
Stdout tab. 


hello world! 4] 


44] eh f\ Build \, stdout |<] | = 


‘DSP RUNNING For Help, press F1 ‘Ln 1, Col 1 
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Changing Program Options and Fixing Syntax Errors 


In the previous section, the portion of the program enclosed by the 
preprocessor commands (#ifdef and #endif) did not run because FILEIO was 
undefined. In this section, you set a preprocessor option with Code 
Composer Studio. You also find and correct a syntax error. 


1) 
2) 


Choose Project>Options. 


In the Compiler tab of the Build Options window, select Symbols from the 


Category list. Type FILEIO in the Define Symbols box. Press the Tab key. 


Notice that the compiler command at the top of the window now includes 
the -d option. The code after the #ifdef FILEIO statement in the program 
is now included when you recompile the program. (The other options may 
vary depending on the DSP board you are using.) 


Build Options xX 


Compiler | Assembler | Linker | 


-g-as -ffC:\tivmyprojects\hellol -dFILEIO 


Include Search Path 
[- Suppress Banner 


IV Generate Symbolic Debug Infomatio 


Command Extension File 


Preprocessor 


Preprocess and\Compile 


Category: 


Diagnostics (I) 


Symbols 


Define Symbols JFILEIO 
Undefine Symbols 


IV Keep Labels as Symbols 


[ ‘Write out unreferenced externs 


i Cancel | Help | 
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3) Click OK to save your new option settings. 


4) Choose Project>Rebuild All or click the (Rebuild All) toolbar button. 
You need to rebuild all the files whenever the project options change. 


5) A message says the program contains compile errors. Click Cancel. 
Scroll up in the Build tab area. You see a syntax error message. 


c1500 -g -as -dFILEIO -frC:\TINMYPROJECTSSHELLO1 HELLO.C 4} 

[hello.c] 

TMS320C54x ANSI C Compiler Version 3.10 

Copyright (c) 1996-1995 Texas Instruments Incorporated | 
"hella.c" ==> main 

"HELLO.C", line 53: error: expected a ";" = 

WATS TM, Buia / lI] Pic 


6) Double-click on the red text that describes the location of the syntax error. 
Notice that the hello.c source file opens, and your cursor is on the 
following line: 


fileStr[i] = 0; 
7) Fix the syntax error. (The semicolon is missing.) Notice that an asterisk 
(*) appears next to the filename in the Edit window's title bar, indicating 


that the source file has been modified. The asterisk disappears when the 
file is saved. 


8) Choose File-Save or press Cirl+S to save your changes to hello.c. 


Code Composer Studio rebuilds files that have been updated. 


Using Breakpoints and the Watch Window 


2.6 Using Breakpoints and the Watch Window 


When you are developing and testing programs, you often need to check the 
value of a variable during program execution. In this section, you use 
breakpoints and the Watch Window to view such values. You also use the 
step commands after reaching the breakpoint. 


1) 
2) 


Choose File-Reload Program. 


Double-click on the hello.c file in the Project View. You may want to make 
the window larger so that you can see more of the source code at once. 


Put your cursor in the line that says: 
fprintf(fptr, "Ss", scanStr); 
Click the “ (Toggle Breakpoint) toolbar button or press F9. The line is 


highlighted in magenta. (If you like, you can change this color using 
Option—Color.) 


Choose View—Watch Window. A separate area in the lower-right corner 
of the Code Composer Studio window appears. At run time, this area 
shows the values of watched variables. 


Right-click on the Watch Window area and choose Insert New 
Expression from the pop-up list. 


Type *scanStr as the Expression and click OK. 


Watch Add Expression |x| 
Expression: [fscanSt 


Notice that *scanStr is listed in the Watch Window but is undefined. This 
is because the program is currently not running in the main() function 
where this variable is declared locally. 


*scanStr = unknown identifier 


41> PI, watch 1 A Wail] «|_| of 


Choose Debug—Run or press F5. 
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10) At the prompt, type goodbye and click OK. Notice that the Stdout tab 
shows the input text in blue. 


Standard Input Dialog Box |X 
Please enter your input : 


goodbye a 


Also notice that the Watch Window now shows the value of *scanStr. 


*scanstr = goodbye 


a> Tbiy watcn 1 A wet|| «|_| Pia 


After you type an input string, the program runs and stops at the 
breakpoint. The next line to be executed is highlighted in yellow. 


11) Click the {* (Step Over) toolbar button or press F10 to step over the call 


to fprintf(). 


12) Experiment with the step commands Code Composer Studio provides: 


m & Step Into (F8) 

m { Step Over (F10) 

m {} Step Out (Shift F7) 

m “(Run to Cursor (Ctrl F10) 


13) Click * (Run) or press F5 to finish running the program when you have 


finished experimenting. 


Using the Watch Window with Structures 


2.7 Using the Watch Window with Structures 


In addition to watching the value of a simple variable, you can watch the 
values of the elements of a structure. 


1) Right-click on the Watch Window area and choose Insert New 
Expression from the pop-up list. 


2) Type str as the Expression and click OK. A line that says +str = {...} 
appears in the Watch Window. The + sign indicates that this is a structure. 
Recall from section 2.3, page 2-4 that a structure of type PARMS was 
declared globally and initialized in hello.c. The structure type is defined in 
hello.h. 


3) Click once on the + sign. Code Composer Studio expands this line to list 
all the elements of the structure and their values. (The address shown for 
Link may vary.) 


Watch Window 


Beta = 2934 
EchoPower = 9432 


ErrorPower = ?213 
Ratio = 9432 
+Link = OxO05FO 


4] > [pi], watch 1 A Watch 2 vw «| | 


4) Double-click on any element in the structure to open the Edit Variable 
window for that element. 


5) Change the value of the variable and click OK. Notice that the value 
changes in the Watch Window. The value also changes color to indicate 
that you have changed it manually. 


6) Select the str variable in the Watch Window. Right-click in the Watch 
Window and choose Remove Current Expression from the pop-up list. 
Repeat this step for all expressions in the Watch Window. 


7) Right-click on the Watch Window and choose Hide from the pop-up menu 
to hide the window. 


8) Choose Debug—Breakpoints. In the Breakpoints tab, click Delete All and 
then click OK. 
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2.8 Profiling Code Execution Time 


In this section, you use the profiling features of Code Composer Studio to 
gather statistics about the execution of the standard puts() function. In section 
3.4, page 3-8, you compare these results to the results for using the 
DSP/BIOS API to display the hello world message. 


1) Choose File-Reload Program. 


2) Choose Profiler-+Enable Clock. A check mark appears next to this item 
in the Profiler menu. This clock counts instruction cycles. It must be 
enabled for profile-points to count instruction cycles. 


3) Double-click on the hello.c file in the Project View. 


4) Choose View-Mixed Source/ASM. Assembly instructions are listed in 
gray following each C source code line. 


5) Put your cursor in the line that says: 


puts("hello world! \n"); 


6) Click the @) (Toggle Profile-point) toolbar button. The C source code line 
and the first assembly instruction are highlighted in green. 


7) Scroll down and put your cursor in the line that says: 


for (i = 0; i < BUFSIZE; i++) { 


8) Click the €) (Toggle Profile-point) toolbar button. (Or, right-click on the 
code line and choose Toggle Profile Pt from the pop-up menu.) 


a hello.c |. {OF x] 


7*® write a string ta stdout */ 


NO00:1404 FO20 #640h,0 


#ifdef FILEIO 
7* clear char arrays */ 


0000 
no00 
noog: neo4 
0000 F847 
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Profile-points are handled before the profile-point line is executed. They 
report the number of instruction cycles since the previous profile-point or 
since the program started running. As a result, the statistics for the 
second profile-point report the number of cycles from when puts() started 
executing until it finished executing. 


9) Choose Profiler—>View Statistics. An area appears at the bottom of the 
window that displays statistics about the profile-points. 


10) Resize this area by dragging its edges so that you can see all the 


columns. 
Freesat aces [vcr [nee eee eae 
HELLO.C line 47 0. 0 
HELLO.C line 51 ; 0.0 : ; al 


‘Note: Line Numbers May Vary 


Line numbers displayed in screen shots in this manual may vary from those 


displayed in the current release of the software. 
L 


11) Click the * (Run) toolbar button or press F5 to run the program. Type 
an input string in the prompt window. 


12) Notice the number of cycles shown for the second profile-point. It should 
be about 2800 cycles. (The actual numbers shown may vary.) This is the 
number of cycles required to execute the call to puts(). 


Profile Statistics 


[Location | Count | Average] Total] Maximum] Minimum| 


HELLO.C line 47 931.0 aa 931 
HELLO.C line 51 2618.0 2816 2616 


The average, total, maximum, and minimum are the same for these 
profile-points because these instructions are executed only one time. 


‘Note: Target Halts at Profile-Points 


Code Composer Studio temporarily halts the target whenever it reaches a 
profile-point. Therefore, the target application may not be able to meet 
real-time deadlines when you are using profile-points. (Real-time 


monitoring can be performed using RTDX. See section 1.5, page 1-12.) 
| 


Developing a Simple Program 2-13 


Things to Try 


13) Before proceeding to the next chapter (after completing section 2.9, page 
2-14), perform the following steps to free the resources used in your 
profiling session: 


MH Go to the Profiler menu and uncheck Enable Clock. 


M@ Close the Profile Statistics window by right-clicking and choosing 
Hide from the pop-up menu. 


H@ Go to Profiler—Profile-points. Select Delete All and click OK. 


HM Go to the View menu and uncheck Mixed Source/ASM. 


2.9 Things to Try 


To further explore Code Composer Studio, try the following: 


1) In the Build Options window, examine the fields on the Compiler, 
Assembler, and Linker tabs. Notice how changing the values in the field 
affects the command line shown. You can see the online help to learn 
about the various command line switches. 


11 Set some breakpoints. Choose Debug—Breakpoints. In the Breakpoint 
type box, notice that you can also set conditional breakpoints that break 
only if an expression is true. You can also set a variety of hardware 
breakpoints. 


2.10 Learning More 
To learn more about using Code Composer Studio, see the online help for 


Code Composer Studio or the Code Composer Studio User’s Guide (which is 
provided as an Adobe Acrobat file). 
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Developing a DSP/BIOS Program 


This chapter introduces DSP/BIOS and shows how to create, build, debug, 
and test programs that use DSP/BIOS. 


In this chapter, you optimize the hello world program you created in Chapter 
2 by using DSP/BIOS. 


This chapter requires a physical board and cannot be carried out using a 


software simulator. Also, this chapter requires the DSP/BIOS components of 
Code Composer Studio. 
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3.1 
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Creating a Configuration File 


Another way to implement the hello world program is to use the LOG module 
provided with the DSP/BIOS API. You can use the DSP/BIOS API to provide 
basic run-time services within your embedded programs. The API modules 
are optimized for use on real-time DSPs. Unlike C library calls such as puts(), 
DSP/BIOS enables real-time analysis without halting your target hardware. 
Additionally, the API code consumes less space and runs faster than C 
standard I/O. A program can use one or more DSP/BIOS modules as desired. 


In this chapter, you modify the files from Chapter 2 to use the DSP/BIOS API. 
(If you skipped Chapter 2, follow the steps in section 2.1, page 2-2 and 
section 2.2, page 2-3.) 


In order to use the DSP/BIOS API, a program must have a configuration file 
that defines the DSP/BIOS objects used by the program. In this section, you 
create a configuration file. 


1) If you have closed Code Composer Studio, restart it and use 
Project>Open to reopen the myhello.mak project in the 
c:\tiimyprojects\hello1 folder. (If you installed elsewhere, open the folder 
within the myprojects folder in the location where you installed.) 


2) Choose File+New-—DSP/BIOS Config. 


3) Select the template for your DSP board and click OK. (The TMS320C54x 
DSP/BIOS User's Guide explains how to create a custom template.) 


Creating a Configuration File 


You see a window like the following. You can expand and contract the list 
by clicking the + and - symbols on the left. The right side of the window 
shows properties of the object you select in the left side of the window. 


ee ee fol x| 
Estimated Data Size: 52 Est. Min. Stack Size (MA4Us}: 33 | LOG - Event Log Manager properties 


Project Manager e 
1] Global Settings Object Memory IDATA 
£ CLK - Clock Manager 

~ [BM HST - Host Channel Manager 

(F] a, Hiwil - Hardware Interrupt Service Routine Manager 

[+] '§) IDL - Idle Function Manager 

=| (4 LOG - Event Log Manager 

~-@) LOG_system 


[+ 


+) MEM - Memory Section Manager 
x PIP - Buffered Pipe Manager 
© PAD - Periodic Function Manager 
RTDX - Real-Time Data Exchange Settings 
a STS - Statistics Object Manager 
$F SWI - Software Interrupt Manager 


+ 


4) Right-click on the LOG - Event Log Manager and choose Insert LOG from 
the pop-up menu. This creates a LOG object called LOGO. 


5) Right-click on the name of the LOGO object and choose Rename from the 
pop-up menu. Change the object’s name to trace. 


= ea LOG - Event Log Manager 
@& LOG_system 


6) Choose File>Save. Move to your working folder (usually 
c:\ti\myprojects\hello1) and save the configuration as myhello.cdb. 
Saving this configuration actually creates the following files: 


m@ myhello.cdb. Stores configuration settings 

m@ myhellocfg.cmd. Linker command file 

m@ myhellocfg.s54. Assembly language source file 
| 


myhellocfg.h54. Assembly language header file included by 
myhellocfg.s54 
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Adding DSP/BIOS Files to a Project 


Recall that the configuration file you made in the previous section actually 
resulted in the creation of four new files: myhello.cdo, myhellocfg.cmd, 
myhellocfg.s54, and myhellocfg.n54. In this section, you add these files to 
your project and remove the files which they replace. 


1) 


Choose Project—Add Files to Project. Select Configuration File (*.cdb) in 
the Files of type box. Select the myhello.cdb file and click Open. Notice 
that the Project View now contains myhello.cdb in a folder called 
DSP/BIOS Config. In addition, the myhellocfg.s54 file is now listed as a 
source file. Remember that Code Composer Studio automatically adds 
include files (in this case, the myhellocfg.h54 file) to the project when it 
scans for dependencies during a project build. 


The output filename must match the .cdb filename (myhello.out and 
myhello.cdb). Go to Project>Options and choose the Linker tab. In the 
Output Filename field, verify that myhello.out is the filename and click 
OK. 


Choose Project>Add Files to Project again. Select Linker Command File 
(*.cmd) in the Files of type box. Select the myhellocfg.cmd file and click 
Open. This causes Code Composer Studio to display the following 
warning: 


Code Composer 


Warning, Only one linker command file [*.cmd] 
can be added to the project. 
Do you wish to replace the file "HELLO.CMD" 


with file "'myhellocfg.cmd"™ 
; No | 


Click Yes. This replaces the previous command file (HELLO.CMD) with 
the new one that was generated when you saved the configuration. 


In the Project View area, right-click on the vectors.asm source file and 
choose Remove from project in the pop-up menu. The hardware interrupt 
vectors are automatically defined by the DSP/BIOS configuration file. 


Right-click on the RTS.lib library file and remove it from the project. This 
library is automatically included by the myhellocfg.cmd file. 


Double-click on the hello.c program to open it for editing. If the assembly 
instructions are shown, choose View-Mixed Source/ASM to hide the 
assembly code. 


8) 


Adding DSP/BIOS Files to a Project 


Change the source file’s contents to the following. (You can copy and 
paste this code from c:\ti\c5400\tutorial\hello2\hello.c if you like.) Make 
sure you replace the existing main function (which has the puts() function) 
with the main shown below, because puts() and LOG_printf use the same 
resources. 


/* DSP/BIOS header files*/ 
#include <std.h> 
#include <log.h> 


/* Objects created by the Configuration Tool */ 
extern LOG_Obj trace; 


/* 


main ay 


Void main () 


{ 


} 


LOG_printf(&trace, "hello world!"); 


/* fall into DSP/BIOS idle loop */ 
return; 


Notice the following parts of this code: 


a) 


The code includes the std.h and log.h header files. All programs that 
use the DSP/BIOS API must include the std.h file and header files for 
any modules the program uses. The log.h header file defines the 
LOG_Obj structure and declares the API operations in the LOG 
module. The std.h file must be included first. The order of the 
remaining modules you include is not important. 


The code then declares the LOG object you created in the 
configuration file. 


Within the main function, this example calls LOG_printf and passes 
it the address of the LOG object (&trace) and the hello world 
message. 


Finally main returns, which causes the program to enter the 
DSP/BIOS idle loop. Within this loop, DSP/BIOS waits for software 
interrupts and hardware interrupts to occur. Chapter 5 through 
Chapter 7 explain these types of events. 


10) Choose File-Save or press Cirl+S to save your changes to hello.c. 


11) Choose Project-Options. Remove FILEIO from the Define Symbols box 
in the Compiler tab. Then click OK. 


12) Choose Project—Rebuild All or click the (Rebuild All) toolbar button. 


Developing a DSP/BIOS Program 3-5 


Testing with Code Composer Studio 


3.3 


3-6 


Testing with Code Composer Studio 


Now you can test the program. Since the program writes only one line to a 
LOG, there is not much to analyze. Chapter 5 through Chapter 7 show more 
ways to analyze program behavior. 


Choose File-Load Program. Select the program you just rebuilt, 
myhello.out, and click Open. 


Choose Debug—>Go Main. 


Choose Tools >DSP/BIOS—>Message Log. A Message Log area appears 
at the bottom of the Code Composer Studio window. 


Right-click on the Message Log area and choose Property Page from the 
pop-up window. 


Select trace as the name of the log to monitor and click OK. The default 
refresh rate is once per second. (To change refresh rates, choose 
Tools >DSP/BIOS—RITA Control Panel. Right-click on the RTA Control 
Panel area and choose Property Page. Choose a new refresh rate and 
click OK.) 


Choose Debug—Run or press F5. 


The hello world message appears in the Message Log area. 


0 hello world! 


Choose Debug—Halt or press Shift F5 to stop the program. After the main 
function returns, your program is in the DSP/BIOS idle loop, waiting for 
an event to occur. See section 3.5, page 3-10 to learn more about the idle 
loop. 


Close the Message Log by right-clicking and selecting Close. This is 
necessary because you will use the Profiler in the next section. 


Go to Tools>RTDX to launch the RTDX plug-in. Select RTDX disable 
from the pull-down list, then right-click and select Hide. 


Testing with Code Composer Studio 


‘Note: Profiling and RTDX Cannot Be Used Together on Some Targets 


On some DSP targets you cannot use both profiling and RTDX at the same 
time. Close any tool that uses RTDX, such as the Message Log or any other 
DSP/BIOS plug-ins, before using profiling. To ensure that RTDX is disabled, 
especially after using DSP/BIOS plug-ins, go to Tools >RTDX to launch the 
RTDX plug-in. Select RTDX disable from the pull-down list, then right-click 
and select Hide. Conversely, after profiling, free the profiler resources 
before using RTDX, as described in section 2.8, page 2-14. 


The following error message results when you attempt simultaneous use: 


CPU - DSP Device Driver Ed 


GTI device driver failed to enable RTD 
Resource conflict: 
Verify that resource is not already in use 
by Profiler. RTD, RealTime or Emulator Analysis 


Cancel | 
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Profiling DSP/BIOS Code Execution Time 


Earlier, you used the profiling features of Code Composer Studio to find the 
number of cycles required to call puts(). Now, you can do the same for the call 
to LOG_printt. 


1) 
2) 


8) 
9) 


Choose File-Reload Program. 


Choose Profiler+Enable Clock. Make sure you see a check mark next to 
this item in the Profiler menu. 


Double-click on the hello.c file in the Project View. 


Choose View—Mixed Source/ASM. Assembly instructions are listed in 
gray following each C source code line. 
Put your cursor in the line that says: 


LOG_printf(&trace, "hello world!"); 


Click the €) (Toggle Profile-point) toolbar button. This line and the 
assembly language instruction that follows it are highlighted in green. 


Scroll down and put your cursor in the line for the final curly brace of the 
program, and click the €) (Toggle Profile-point) toolbar button. 


You might think that you should set the second profile-point on the line 
that says return; since that is the last statement in the program. 
However, notice that there are no assembly language equivalents shown 
until after the curly brace. If you set the profile-point at the line that says 
return; , Code Composer Studio automatically corrects the problem at 
run time. 


Choose Profiler>View Statistics. 


Click the & (Run) toolbar button or press F5 to run the program. 


10) Notice the number of instruction cycles shown for the second 


profile-point. It should be about 58. (The actual numbers shown may 
vary.) This is the number of cycles required to execute the call to 
LOG_printt. 


HELLO.C line 33 1 56.0 568 56 56 
HELLO.C line 29 1 9273.0 5273 5273 5273 


Profiling DSP/BIOS Code Execution Time 


Calls to LOG_printf are efficient because the string formatting is 
performed on the host PC rather than on the target DSP. LOG_printf 
takes 58 instruction cycles compared to about 2800 for puts() measured 
at the end of Chapter 2. You can leave calls to LOG_printf in your code 
for system status monitoring with very little impact on code execution. 


11) Click & (Halt) or press Shift F5 to stop the program. 


12) Before proceeding to the next chapter (after completing section 3.5, page 
3-10), perform the following steps to free the resources used in your 
profiling session: 


MH Go to the Profiler menu and uncheck Enable Clock. 


M Close the Profile Statistics window by right-clicking and choosing 
Hide from the pop-up menu. 


Go to Profiler—Profile-points. Select Delete All and click OK. 
Go to the View menu and uncheck Mixed Source/ASM. 


Close all source and configuration windows. 


Go to Project-Close to close the project. 
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Things to Try 


To explore Code Composer Studio, try the following: 


| 


Learning More 


Load myhello.out and put a breakpoint on the line that calls LOG_printf. 
Use Debug-—Breakpoints to add a breakpoint at IDL_F_loop. (Type 
IDL_F_loop in the Location box and click Add.) 


Run the program. At the first breakpoint, use View—CPU 
Registers->CPU Register to see a list of register values. Notice that INTM 
is 1, indicating that interrupts are disabled while the main function is 
executing. 


Run to the next breakpoint. Notice that INTM is now 0, indicating that 
interrupts are now enabled. Notice that if you run the program, you hit this 
breakpoint over and over. 


After the startup process and main are completed, a DSP/BIOS 
application drops into a background thread called the idle loop. This loop 
is managed by the IDL module and continues until you halt the program. 
The idle loop runs with interrupts enabled and can be preempted at any 
point by any ISR or software interrupt triggered to handle the application’s 
real-time tasks. Chapter 5 through Chapter 7 explain more about using 
ISRs and software interrupts with DSP/BIOS 


In an MS-DOS window, run the sectti.exe utility by typing the following 
command lines. Change the directory locations if you installed Code 
Composer Studio in a location other than c:\ti. 

ed ¢c:\ti\c5400\tutorial\hellol 

sectti hello.out > hellol.prn 


cd ..\hello2 
sectti hello.out > hello2.prn 


Compare the hello1.prn and hello2.prn files to see the differences in 
memory sections and sizes when using stdio.h calls and DSP/BIOS. 
Notice that the size of the .text section is smaller for the DSP/BIOS call to 
LOG_printf, as compared to linking the stdio when using puts(). See the 
TMS320C54x DSP/BIOS User's Guide for more information on the sectti 
utility. 


To learn more about using Code Composer Studio and DSP/BIOS, see the 
online help for Code Composer Studio. In addition, see the Code Composer 
Studio User’s Guide and the TMS320C54x DSP/BIOS User's Guide (which 
are provided as Adobe Acrobat files). 


Chapter 4 


Testing Algorithms and Data from a File 


This chapter shows the process for creating and testing a simple algorithm 
and introduces additional Code Composer Studio features. 


In this chapter, you create a program that performs basic signal processing. 
You expand on this example in the following two chapters. 


You create and test a simple algorithm using data stored in a file on your PC. 
You also use Probe Points, graphs, animation, and GEL files with Code 
Composer Studio. 
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Opening and Examining the Project 


You begin by opening a project with Code Composer Studio and examining 
the source code files and libraries used in that project. 


If you installed Code Composer Studio in c:\ti, create a folder called 
volume in the c:\tiimyprojects folder. (If you installed elsewhere, create 
a folder within the myprojects folder in the location where you installed.) 


Copy all files from the c:\ti\c5400\tutorial\volume1 folder to this new folder. 


If Code Composer Studio is not already running, from the Windows Start 
menu, choose Programs—>Code Composer Studio 'C5400-—CCStudio. 


Choose Project-Open. Select the volume.mak file in the folder you 
created and click Open. 


Code Composer Studio displays a dialog box indicating the library file 
was not found. This is because the project was moved. To locate this file, 
click the Browse button, navigate to c:\ti\c5400\cgtools\lib, and select 
rts.lio. (If you installed somewhere other than c:\ti, navigate to the 
\c5400\cgtools\lib folder within the folder where you installed.) 


Code Composer Studio ES 


AN File "C:\ti\cgtools\lib\rts. lib" was not found. 


Ignore | Ignore All Remove | 


6) 


Expand the Project View by clicking 


the + signs next to Project, 
VOLUME.MAK, Include, Libraries, 
and Source. 


The files used in this project are: 


HM volume.c. This is the source code 
for the main program. You 
examine the source code in the 
next section. 


H@ volume.h. This is a header file 
included by volume.c to define 
various constants and structures. 


m@ load.asm. This file contains the 
load routine, a simple assembly 
loop routine that is callable from C 
with one argument. It consumes 


Opening and Examining the Project 


Files 
GEL files 
5 
iS VOLUME.MAK 
DSP/BIOS Config 
( Include 
VOLUME.H 
STDIO.H 


RTS.LIB 

S| Source 
LOAD.ASM 
VECTORS.ASM 
VOLUME.C 

YOLUME.CMDB 


(31*argument) + 13 instruction cycles. 


M@ vectors.asm. This is the same file used in Chapter 2 to define a reset 
entry point in the DSP’s interrupt vector table. 


mM volume.cmd. This linker command file maps sections to memory. 


@ rts.lib. This library provides run-time support for the target DSP. 
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Reviewing the Source Code 


4.2 Reviewing the Source Code 


Double-click on the volume.c file in the Project View to see the source code 
in the right half of the Code Composer Studio window. 


Notice the following parts of this example: 


L) After the main function prints a message, it enters an infinite loop. Within 
this loop, it calls the datalO and processing functions. 


1 The processing function multiplies each value in the input buffer by the 
gain and puts the resulting values into the output buffer. It also calls the 
assembly load routine, which consumes instruction cycles based on the 
processingLoad value passed to the routine. 


1 The datalO function in this example does not perform any actions other 
than to return. Rather than using C code to perform I/O, you can use a 
Probe Point within Code Composer Studio to read data from a file on the 
host into the inp_buffer location. 


#include <stdio.h> 
#include "volume.h" 
/* Global declarations */ 


int inp_buffer[BUFSIZE]; 
int out_buffer[BUFSIZE 


/* processing data buffers */ 


’ 
, 


int gain = MINGAIN; /* volume control variable */ 
unsigned int processingLoad = BASELOAD; /* processing load */ 


/* Functions */ 
extern void load(unsigned int loadValue) ; 


static int processing(int *input, int *output); 
static void datalIO(void); 


Le main */ 
void main() 


{ 
int *input = &inp_buffer[0]; 
int *output = s&out_buffer[0]; 


puts ("volum xample started\n"); 


Reviewing the Source Code 


/* loop forever */ 
while (TRUE) 
{ 


/* Read using a Probe Point connected to a host file. */ 
datalO(); 


/* apply gain */ 
processing(input, output); 


{eX  sssS=5== processing ======== # 
* FUNCTION: apply signal processing transform to input signal. 
* PARAMETERS: address of input and output buffers. 
* RETURN VALUE: TRUE. */ 

static int processing(int *input, int *output) 


{ 


int size = BUFSIZE; 


while (size-——) { 
*xoutputt+ = *inputt+ * gain; 


} 


/* additional processing load */ 
load (processingLoad) ; 


return (TRUE) ; 


/* sssss=== datalO ======== * 

* FUNCTION: read input signal and write output signal. 
* PARAMETERS: none. 

* RETURN VALUE: none. */ 

static void dataI0O() 

{ 


/* do data I/O */ 
return; 
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Adding a Probe Point for File I/O 


In this section, you add a Probe Point, which reads data from a file on your 
PC. Probe Points are a useful tool for algorithm development. You can use 
them in the following ways: 


1) To transfer input data from a file on the host PC to a buffer on the target 
for use by the algorithm 


1 To transfer output data from a buffer on the target to a file on the host PC 
for analysis 


1 To update a window, such as a graph, with data 


Probe Points are similar to breakpoints in that they both halt the target to 
perform their action. However, Probe Points differ from breakpoints in the 
following ways: 


11 Probe Points halt the target momentarily, perform a single action, and 
resume target execution. 


(1 Breakpoints halt the CPU until execution is manually resumed and cause 
all open windows to be updated. 


1 Probe Points permit automatic file input or output to be performed; 
breakpoints do not. 


This chapter shows how to use a Probe Point to transfer the contents of a PC 
file to the target for use as test data. It also uses a breakpoint to update all the 
open windows when the Probe Point is reached. These windows include 
graphs of the input and output data. Chapter 7 shows two other ways to 
manage input and output streams. 


1) Choose Project>Rebuild All or click the (Rebuild All) toolbar button. 


2) Choose File-Load Program. Select the program you just rebuilt, 
volume.out, and click Open. 


3) Double-click on the volume.c file in the Project View. 
4) Put your cursor in the line of the main function that says: 


datalI0O(); 


The datalO function acts as a placeholder. You add to it later. For now, it 
is aconvenient place to connect a Probe Point that injects data from a PC 
file. 


5) Click the er (Toggle Probe Point) toolbar button. The line is highlighted 
in blue. 


Adding a Probe Point for File I/O 


Choose File-File I/O. The File I/O dialog appears so that you can select 
input and output files. 


In the File Input tab, click Add File. 
Choose the sine.dat file. 


Notice that you can select the format of the data in the Files of Type box. 
The sine.dat file contains hex values for a sine waveform. 


Click Open to add this file to the list in the File I/O dialog. 


A control window for the sine.dat file appears. (It may be covered by the 
Code Composer Studio window.) Later, when you run the program, you 
can use this window to start, stop, rewind, or fast forward within the data 
file. 


> Ewe] kK | >» 


10) In the File I/O dialog, change the Address to inp_buffer and the Length to 


100. Also, put a check mark in the Wrap Around box. 


File 170 Ea 


File Input | File Qutput | 


C:\tivmyprojects‘\volumel ‘\sine. dat Add File 
Remove File | 


Probepoint: [Not Connected Page: [Data 7] 
Address: Jinp_butfer 
Lenath: fi oo Add Probepoint | 


OK | Cancel | Apply | Help | 


m The Address field specifies where the data from the file is to be 
placed. The inp_buffer is declared in volume.c as an integer array of 
BUFSIZE. 
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M@ The Length field specifies how many samples from the data file are 
read each time the Probe Point is reached. You use 100 because that 
is the value set for the BUFSIZE constant in volume.h (0x64). 


mM The Wrap Around option causes Code Composer Studio to start 
reading from the beginning of the file when it reaches the end of the 
file. This allows the data file to be treated as a continuous stream of 
data even though it contains only 1000 values and 100 values are 
read each time the Probe Point is reached. 


11) Click Add Probe Point. The Probe Points tab of the Break/Probe/Profile 
Points dialog appears. 


12) Highlight the Probe Point you created in step 5. 


13) In the Connect To field, click the down arrow and select the sine.dat file 
from the list. 


14) Click Replace. The Probe Point list changes to show that this Probe Point 
is connected to the sine.dat file. 


15) Click OK. The File I/O dialog shows that the file is now connected to a 
Probe Point. 


16) Click OK in the File I/O dialog. 
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Displaying Graphs 


If you ran the program now, you would not see much information about what 
the program was doing. You could set watch variables on addresses within 
the inp_buffer and out_buffer arrays, but you would need to watch a lot of 
variables and the display would be numeric rather than visual. 


Code Composer Studio provides a variety of ways to graph data processed 
by your program. In this example, you view a signal plotted against time. You 
open the graphs in this section and run the program in the next section. 


1) Choose View>Graph—Time/Frequency. 


2) In the Graph Property Dialog, change the Graph Title, Start Address, 
Acquisition Buffer Size, Display Data Size, DSP Data Type, Autoscale, 
and Maximum Y-value properties to the values shown here. Scroll down 
or resize the dialog box to see all the properties. 


= Graph Property Dialog xX! 


Display Type Single Time 

Graph Title Input Buffer 

Start Address inp_buffer 

Page Data 

Acquisition Buffer Size 100 

Index Increment 1 

Display Data Size 100 

DSP Data Type 16-bit signed intd Change 
Q-value 0 these 
Sampling Rate (Hz) 1 properties 
Plot Data From Left to Right 

Left-shifted Data Display ‘Yes 

Autoscale Off 

DC Value oO 

Maximum ‘Y-value 1000 


Cancel | Help | 


3) Click OK. A graph window for the Input Buffer appears. 


4) Right-click on the Input Buffer window and choose Clear Display from the 
pop-up menu. 


5) Choose View—Graph—Time/Frequency again. 


6) This time, change the Graph Title to Output Buffer and the Start Address 
to out_buffer. All the other settings are correct. 


7) Click OK to display the graph window for the Output Buffer. Right-click on 
the graph window and choose Clear Display from the pop-up menu. 
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Animating the Program and Graphs 


So far, you have placed a Probe Point, which temporarily halts the target, 
transfers data from the host PC to the target, and resumes execution of the 
target application. However, the Probe Point does not cause the graphs to be 
updated. In this section, you create a breakpoint that causes the graphs to be 
updated and use the Animate command to resume execution automatically 
after the breakpoint is reached. 


1) 
2) 


In the Volume.c window, put your cursor in the line that calls datalO. 


Click the “ (Toggle Breakpoint) toolbar button or press F9. The line is 
highlighted in both magenta and blue (unless you changed either color 
using Option—Color) to indicate that both a breakpoint and a Probe Point 
are set on this line. 


You put the breakpoint on the same line as the Probe Point so that the 
target is halted only once to perform both operations—transferring the 
data and updating the graphs. 


Arrange the windows so that you can see both graphs. 
Click the & (Animate) toolbar button or press F12 to run the program. 


The Animate command is similar to the Run command. It causes the 
target application to run until it reaches a breakpoint. The target is then 
halted and the windows are updated. However, unlike the Run command, 
the Animate command then resumes execution until it reaches another 
breakpoint. This process continues until the target is manually halted. 
Think of the Animate command as a run-break-continue process. 


Notice that each graph contains 2.5 sine waves and the signs are 
reversed in these graphs. Each time the Probe Point is reached, Code 
Composer Studio gets 100 values from the sine.dat file and writes them 
to the inp buffer address. The signs are reversed because the input 


Animating the Program and Graphs 


buffer contains the values just read from sine.dat, while the output buffer 
contains the last set of values processed by the processing function. 


=* Output Buffer 


50.0 75.0 99.0 


(50, 98) Time ‘Lin | Fixed Scale 


‘Note: Target Halts at Probe Points 


Code Composer Studio briefly halts the target whenever it reaches a Probe 
Point. Therefore, the target application may not meet real-time deadlines if 
you are using Probe Points. At this stage of development, you are testing 
the algorithm. Later, you analyze real-time behavior using RTDX and 
DSP/BIOS. 


The graphs can also be updated using only Probe Points and the Run 
command. See section 4.10, page 4-18 at the end of this chapter to try 
animating the graphs using Probe Points only. 
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4.6 Adjusting the Gain 
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Recall from section 4.2, page 4-4 that the processing function multiplies each 
value in the input buffer by the gain and puts the resulting values into the 
output buffer. It does this by performing the following statement within a while 
loop: 

*outputt+ = *inputt+t+ * gain; 


This statement multiplies a value in inp_buffer by the gain and places it in the 
corresponding location in the out_buffer. The gain is initially set to MINGAIN, 
which is defined as 1 in volume.h. To modify the output, you need to change 
gain. One way to do this is to use a watch variable. 


1) Choose View>Watch Window. 


2) Right-click on the Watch window area and choose Insert New Expression 
from the pop-up list. 


3) Type gain as the Expression and click OK. 
Watch Add Expression Ea 
Expression: [gain 


The value of this variable appears in the Watch window area. 


4) If you have halted the program, click the Py (Animate) toolbar button to 
restart the program. 


5) Double-click on gain in the Watch window area. 
6) Inthe Edit Variable window, change the gain to 10 and click OK. 


7) Notice that the amplitude of the signal in the Output Buffer graph changes 
to reflect the increased gain. 


= _- |} x! 


50.0 75.0 99.0 


/(50, 980) Time ‘Lin (Fixed Scale 
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4.7 Viewing Out-of-Scope Variables 


You have used the Watch Window to view and change the values of variables. 
Sometimes you want to examine variables when they are not currently in 
scope at the current breakpoint. You can do this by using the call stack. 


1) 
2) 


Click & (Halt) or press Shift F5 to stop the program. 


Review the volume.c program within Code Composer Studio (or by 
looking at section 4.2, page 4-4). Notice that *input is defined in both the 
main and processing functions. However, it is not defined within the 
datalO function. 


In the Volume.c window, put your cursor on the line that says return; 
within the datalO function. 


Click the ¥ (Toggle Breakpoint) toolbar button or press F9. The line is 
highlighted in magenta to indicate that a breakpoint is set (unless you 
changed the color using Option—Color). 


Press F5 to run the program. Code Composer Studio automatically 
moves the breakpoint to the next line within that function that corresponds 
to an assembly instruction. It displays a message telling you that it has 
moved the breakpoint. 


Breakpoint Manager | 


iN Some breakpoints are not at valid lines. Code Composer 


has moved these breakpoints to the next valid line 


Click OK. 


Press F5 until the program stops at the breakpoint at the end of the 
datalO function (instead of at the breakpoint on the call to the datalO 
function). 


Right-click on the Watch window area and choose Insert New Expression 
from the pop-up list. 


Type *input as the Expression and click OK. 


Watch Add Expression x] 
Expression: input 
[ Cancel | Help | 
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10) Notice that the Watch window area says this variable is an unknown 
identifier. This shows that *input is not defined within the scope of the 


datalO function. 
11) Choose View->Call Stack. You see the call stack area next to the Watch 


window area. 

gain = 10 = 
main } *input = unknown identifier 
Ox1498 


SPD wate | i 


12) Click on main() in the call stack area to see the value of *input within the 
scope of the main function. (The actual value varies depending on your 
current location within the sine.dat file.) 


gain = 10 


*input =15 4 


TLSLPDP water | | re 


13) You can also click on the address at the bottom of the call stack to see 
that gain is defined globally, but *input is not. (The address varies 
depending on the DSP you are using.) 


14) Right-click on the call stack area and choose Hide from the pop-up menu. 


15) Remove the breakpoint that you added in step 4 by putting he cursor on 
the line after return; in datalO() and clicking the +) (Toggle Breakpoint) 


toolbar button or pressing F9. 


datalo 


0x1496 
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Using a GEL File 


Code Composer Studio provides another way of modifying a variable. This 
method uses GEL, an extension language, to create small windows that allow 
you to modify variables. 


Choose File-Load GEL. In the Load GEL File dialog box, 
select the volume.gel file and click Open. 


Choose GEL-Application Control>Gain. This item was 
added to your menus when you loaded the GEL file. 


If you have halted the program, click the B (Animate) 
toolbar button. Notice that even though the gain is at zero 
your previous gain is still the same. The Gain slider does 
not send a value until it is changed. 


In the Gain window, use the slider to change the gain. The 
amplitude changes in the Output Buffer window. In 
addition, the value of the gain variable in the Watch 
window area changes whenever you move the slider. 


5 


Click & (Halt) or press Shift F5 to stop the program. 


To see how the Gain GEL function works, click the + sign next to GEL 
Files in the Project View. Then, double-click on the VOLUME.GEL file to 
see its contents: 


menuitem "Application Control" 
dialog Load(loadParm "Load") 
{ 


processingLoad = loadParm; 
} 
slider Gain(0, 10 ,1, 1, gainParm) 
{ 

gain = gainParm; 


} 


The Gain function defines a slider with a minimum value of 0, a maximum 
value of 10, and an increment and page up/down value of 1. When you 
move the slider, the gain variable is changed to the new value of the slider 
(gainParm). 
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Adjusting and Profiling the Processing Load 


Profile Statistics 


In 


Chapter 2, you used profile-points to measure the number of cycles 


required to call puts(). Now, you use profile-points to see the effect of 
changing the processingLoad variable, which is passed to the assembly load 
routine. The processingLoad is initially set to BASELOAD, which is defined as 
1 in volume.h. 


9) 


Choose Profiler+Enable Clock. Make sure you see a check mark next to 
this item in the Profiler menu. 


Double-click on the volume.c file in the Project View. 


Choose View—Mixed Source/ASM to view both the C source and the 
equivalent assembly instructions. 


Put your cursor in the assembly instruction after the line that says: 


load(processingLoad) ; 


Click the @) (Toggle Profile-point) toolbar button or right-click and select 
Toggle Profile Pt. 


Put your cursor in the assembly instruction after the line that says: 


return (TRUE 


Click the €) (Toggle Profile-point) toolbar button. 


Choose Profiler>View Statistics. The locations shown identify the 
assembly instructions or addresses where you added the profile-points. 
You may want to resize the Statistics area so that you can see the 
Maximum column. Or, you can right-click on the Statistics area and 
deselect Allow Docking to display the statistics in a separate window. 


Click the Py (Animate) toolbar button or press F12. 


10) Notice the maximum number of cycles shown for the second profile-point. 


It should be about 44 cycles. (The actual numbers shown may vary.) This 
is the number of cycles required to execute the load routine when the 
processingLoad is 1. 


ce Eo 


0x1449 
Ox144D 


29 7343. 6 67964 2344 2332 
26 44.0 1232 44 44 


11) Choose GEL—Application ControlsLoad. 


Adjusting and Profiling the Processing Load 


12) Type 2 as the new load and click Execute. The maximum number of 
cycles for the second profile-point changes to 75. The number of cycles 
increases by 31 when you increment the processingLoad by 1. These 
instruction cycles are performed within the load function, which is stored 
in load.asm. 


Function: Load Ed 
Load [2 


Done | Help | 


13) Right-click on the Profile Statistics area and choose Clear All from the 
pop-up menu. This resets the statistics to 0. The average, maximum, and 
minimum are equal to the number of instruction cycles for the current 
processingLoad. 


14) Click & (Halt) or press Shift F5 to stop the program. 


15) Before proceeding to Chapter 5 (after completing section 4.10, page 
4-18), perform the following steps to free the resources used in your 
profiling session: 


HM Close the Load and Gain controls, the sine.dat control window, and 
the Time/Frequency graphs. 


MH Go to File-File I/O and click Remove File to delete the sine.dat file. 
MH Go to the Profiler menu and uncheck Enable Clock. 


™@ Close the Profile Statistics window by right-clicking and choosing 
Hide from the pop-up menu. 


Go to Debug—Breakpoints. Select Delete All and click OK. 
Go to Debug->Probe Points. Select Delete All and click OK. 
Go to Profiler—Profile-points. Select Delete All and click OK. 
Go to the View menu and uncheck Mixed Source/ASM. 
Close open windows and the project (Project>Close). 


Right-click on volume.gel in the Project View and select Remove. 


Delete all expressions from the Watch Window and hide the Watch 
Window. 
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Things to Try 


To explore using Code Composer Studio, try the following: 


Cy 


Oy 


Learning More 


Add processingLoad to the Watch window. When you use the Load GEL 
control, the processingLoad value is updated in the Watch window. 


Right-click on the Watch window and choose Insert New Expression. 
Click the Help button and read about the display formats you can use. 
Experiment with various display formats. For example, you can type 
*input , x aS the expression to view the sine input in hexadecimal format. 


Change BUFSIZE in volume.h to 0x78 (or 120) and rebuild, then reload 
the program. Change the Length in the File I/O dialog to 0x78. For both 
graphs, change the Acquisition Buffer Size and the Display Data Size to 
0x78. This causes a buffer to contain 3 full sine waves rather than 2.5 
waves. Animate the program and notice that the input and output buffer 
graphs are now in phase. (You may need to halt the program to see 
whether the graphs are in phase.) 


Instead of using profile-points to gather statistics, try using the clock as 
an alternative. Replace the profile-points with breakpoints. Choose 
Profiler>View Clock. Run the program to the first breakpoint. 
Double-click on the clock area to clear it. Run the program again. The 
clock shows the number of cycles it takes to reach the second breakpoint. 


Experiment with Probe Points by repeating section 4.3, page 4-6 through 
section 4.5, page 4-10. This time, use only Probe Points and the Run 
command. Note that you need to create three Probe Points. This is 
because a Probe Point can be associated with only one action. There are 
two graphs to be updated and one file to use as input. Each of these 
actions requires its own Probe Point. 


Also notice that each Probe Point must go on a different line of code. As 
a result, the target is halted three times as often and actions are not 
performed at the same point in target execution. For these reasons, the 
combination of a Probe Point and a breakpoint used in this lesson is more 
efficient than using Probe Points only. 


To practice building projects with Code Composer Studio, copy all the 
files in the c:\ti\c5400\tutorial\volume1 folder to a new folder. Delete the 
volume.mak file. Then, use Code Composer Studio to recreate the 
project using the Project>New and Project-Add Files to Project menu 
items. See section 4.1, page 4-2 for a list of the files to add to the project. 


To learn more about Probe Points, graphs, animation, and GEL files, see the 
online help for Code Composer Studio or the Code Composer Studio User's 
Guide (which is provided as an Adobe Acrobat file). 
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Debugging Program Behavior 


This chapter introduces techniques for debugging a program and several 
DSP/BIOS plug-ins and modules. 


In this chapter, you modify the example from Chapter 4 to create a program 
that schedules its functions and allows for multi-threading. You view 
performance information for debugging purposes. You also use more features 
of DSP/BIOS, including the Execution Graph, the real-time analysis control 
panel (RTA Control Panel), the Statistics View, and the CLK, SWI, STS, and 
TRC modules. 


This chapter requires a physical board and cannot be carried out using a 
software simulator. Also, this chapter requires the DSP/BIOS components of 
Code Composer Studio. 
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Opening and Examining the Project 


You begin by opening a project with Code Composer Studio and examining 
the source code files and libraries used in that project. 


If you installed Code Composer Studio in c:\ti, create a folder called 
volumez in the c:\ti\myprojects folder. (If you installed elsewhere, create 
a folder within the myprojects folder in the location where you installed.) 


2) Copy all files from the c:\ti\c5400\tutorial\volumez2 folder to this new folder. 
3) From the Windows Start menu, choose Programs-+Code Composer 
Studio ’C5400—-CCStudio. 
4) Choose Project>Open. Select the 
volume.mak file in the folder you : 
; GEL files 
created and click Open. Project 
5) Expand the Project View by clicking =| 25 VOLUME. MAK 


the + signs next to Project, 
VOLUME.MAK, DSP/BIOS Config, 
and Source. The volumecfg.cmd 
file, which was created along with a 
configuration file, includes a large 
number of DSP/BIOS header files. 
(You do not need to examine all 


=) DSP/BIOS Config 
YOLUME.CDB 
(9 Include 


(} Libraries 

Ely Source 
LOAD.ASM 
VOLUME.C 


these header files.) 


VOLUMECFG.S54 
VOLUMECFG.CMD 


The files used in this project include: 


m@ volume.cdb. This is the configuration file for the project. 


mM volume.c. This is the source code for the main program. It has been 
revised from the version you used in the previous chapter to support 
using DSP/BIOS in this program. You examine the source code in the 
next section. 


m@ volume.h. This is a header file included by volume.c to define various 
constants and structures. It is identical to the volume.h file used in the 
previous chapter. 


m@ load.asm. This file contains the load routine, a simple assembly loop 
routine that is callable from C with one argument. It is identical to the 
load.asm file used in the previous chapter. 


Mm volumecfg.cmd. This linker command file is created when saving 
the configuration file. 


mM volumecfg.s54. This assembly file is created when saving the 
configuration file. 


M@ volumecfg.h54. This header file is created when saving the 
configuration file. 
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5.2 Reviewing the Source Code 


This example modifies the example from Chapter 4 to introduce real-time 
behavior. Rather than having the main function loop forever, the data I/O in 
the real application is likely to happen as a result of a periodic external 
interrupt. A simple way to simulate a periodic external interrupt in the example 
is to use the timer interrupt from the on-chip timer. 


1) 


2) 


Double-click on the volume.c file in the Project View to see the source 
code in the right half of the Code Composer Studio window. 


Notice the following aspects of the example: 


The data types for declarations have changed. DSP/BIOS provides 
data types that are portable to other processors. Most types used by 
DSP/BIOS are capitalized versions of the corresponding C types. 


The code uses #include to reference three DSP/BIOS header files: 
std.h, log.h, and swi.h. The std.h file must be included before other 
DSP/BIOS header files. 


The objects created in the configuration file are declared as external. 
You examine the configuration file in the next section. 


The main function no longer calls the datalO and processing 
functions. Instead, the main function simply returns after calling 
LOG_printf to display a message. This drops the program into the 
DSP/BIOS idle loop. At this point, the DSP/BIOS scheduler manages 
thread execution. 


The processing function is now called by a software interrupt called 
processing SWI, which yields to all hardware _ interrupts. 
Alternatively, a hardware ISR could perform the signal processing 
directly. However, signal processing may require a large number of 
cycles, possibly more than the time until the next interrupt. Such 
processing would prevent the interrupt from being handled. 
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HM The datalO function calls SWI_dec, which decrements a counter 
associated with a software interrupt object. When the counter 
reaches 0, the software interrupt schedules its function for execution 
and resets the counter. 


The datalO function simulates hardware-based data I/O. A typical 
program accumulates data in a buffer until it has enough data to 
process. In this example, the datalO function is performed 10 times 
for each time the processing function is performed. The counter 
decremented by SWI_dec controls this. 


#include <std.h> 
#include <log.h> 
#include <swi.h> 


#include "volume.h" 
/* Global declarations */ 

Int inp_buffer[BUFSIZE]; /* processing data buffers */ 
Int out_buffer [BUFSIZI 


Int gain = MINGAIN; /* volume control variable */ 
Uns processingLoad = BASELOAD; /* processing load value */ 


/* Objects created by the Configuration Tool */ 
extern LOG_Obj trace; 
extern SWI_Obj processing_SWI; 


/* Functions */ 
extern Void load(Uns loadValue); 


Int processing(Int *input, Int *output); 
Void datalO (Void); 


fe main */ 
Void main () 


{ 


LOG_printf (&trace, "volum xample started\n"); 
/* fall into DSP/BIOS idle loop */ 
return; 
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====SSS> processing ======== * 

FUNCTION: Called from processing_SWI to apply signal 
processing transform to input signal. 

PARAMETERS: Address of input and output buffers. 

RETURN VALUE: TRUE. Ay 


Int processing(Int *input, Int *output) 


{ 


* 
* 
* 
* 
* 
1?) 


Int size = BUFSIZE; 
while (size-——) { 
*xoutputt+ = *inputt+ * gain; 


} 
/* additional processing load */ 
load (processingLoad) ; 


return (TRUE) ; 


S=s====== datalO ======== * 

FUNCTION: Called from timer ISR to fake a periodic 
hardware interrupt that reads in the input 
signal and outputs the processed signal. 

PARAMETERS: none 

RETURN VALUE: none Ay 


Void dataI0O() 


{ 


/* do data I/O */ 


/* post processing_SWI software interrupt */ 
SWI_dec (&processing_SWI) ; 
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Modifying the Configuration File 


Ue he) LF) 


+) 


A DSP/BIOS configuration file has already been created for this example. In 
this section, you examine the objects that have been added to the default 
configuration. 


1) 


2) 


Project Manager 
@ Global Settings 
£6 CLK - Clock Manager 
£t PRD_clock 

£t: datalO_CLK 


In the Project View, double-click on the volume.cdb file (in the DSP/BIOS 
Config folder) to open it. 
Click the + signs next to the CLK, LOG, and SWI managers. This 


configuration file contains objects for these modules in addition to the 
default set of objects in the configuration file. 


Highlight the LOG object called trace. You see the properties for this log 
in the right half of the window. This object’s properties are the same as 
those of the trace LOG you created in section 3.1, page 3-2. The 
volume.c program calls LOG_printf to write volume example started to 
this log. 


trace properties 


comment <add comments here> 
bufseg IDATA, 
buflen [words] 32 
HST - Host Channel Manager logtype circular 
Hw - Hardware Interrupt Service Routine M. | datatype printf 
format Ox%x, Ox%x, Ox%x 


') IDL - Idle Function Manager 
(8 LOG - Event Log Manager 
-@) LOG_system 


One 


i MEM - Memory Section Manager 

2h, PIP - Buffered Pipe Manager 

© PAD - Periodic Function Manager 

fif RTDX - Real-Time Data Exchange Settings 
P| STS - Statistics Object Manager 
$F SWI - Software Interrupt Manager 
“SE processing_S'Wl 


xa 
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4) Right-click on the LOG object called LOG_system. From the pop-up 
menu, select Properties. 


LOG_system Properties Ea 


General 


Comment This object is required by 


bufseg: IDATA, ¥ 
buflen (words) ¥ 
logtype [circular x] 


datatype 


formats 


Cancel | Apply | Help | 


You see the properties dialog for this object. At run time, this log stores 
events traced by the system for various DSP/BIOS modules. 


5) Change the buflen property to 512 words and click OK. 


6) Highlight the CLK object called datalO_CLK. Notice that the function 
called when this CLK object is activated is _datalO. This is the datalO 
function in volume.c. 


Note: Underscores and C Function Names 


This C function name is prefixed by an underscore because saving the 
configuration generates assembly language files. The underscore prefix is 
the convention for accessing C functions from assembly. (See the section 
on interfacing C with assembly language in the TMS320C54x Optimizing C 
Compiler User’s Guide for more information.) 


This rule applies only to C functions you write. You do not need to use the 
underscore prefix with configuration-generated objects or DSP/BIOS API 
calls because two names are automatically created for each object: one 


prefixed with an underscore and one without. 
=== 
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7) 


Since the datalO function is no longer run within main, what causes this 
CLK object to run its function? To find out, right-click on the CLK - Clock 
Manager object. From the pop-up menu, select Properties. You see the 
Clock Manager Properties dialog. 


CLK - Clock Manager Properties Xx! 


General | 


Object Memory: 
JV) Erneble GLK Menager 


IV Use high resolution time for internal timings 


Microseconds/Int: 1000.0 


I~ Directly configure on-chip timer registers 


fo! Fie DOR 
WD Register fi fa 
PRD) Register 49993 


lnstuctons/ nt 100000 


Cancel | Aap Help | 


Notice that there is a check mark in the Enable CLK Manager box. When 
this box is checked, the timer interrupt drives the CLK manager. 


Click Cancel to close the Clock Manager Properties dialog without 
making any changes. 


Expand the list of HWI objects and examine the properties of the 
HWI_TINT object. Its interrupt source is the DSP timer and it runs a 
function called CLK_F_isr when the on-chip timer causes an interrupt. 


The CLK object functions run from the context of the CLK_F_isr hardware 
interrupt function. Therefore, they run to completion without yielding and 
have higher priority than any software interrupts. (The CLK_F_isr saves 
the register context, so the CLK functions do not need to save and restore 
context as would be required normally within a hardware ISR function.) 


Modifying the Configuration File 


10) Right-click on the processing_SWI software interrupt object. From the 
pop-up menu, select Properties. 


processing_SW!I Properties Ed 


General | 


comment: [<add comments here> 
Brianty a 
function: [processing 
mailbox: 10 

arg0: [inp_buffer 
arg1: [_out_buffer 


: Cancel | Apply | Help | 


@ function. When this software interrupt is activated, the processing 
function runs. This function is shown in section 5.2, page 5-5. 


H@ mailbox. The mailbox value can control when a software interrupt 
runs. Several API calls affect the value of the mailbox and can post 
the software interrupt depending on the resulting value. When a 
software interrupt is posted, it runs when it is the highest priority 
software or hardware interrupt task that has been posted. 


@ arg0, arg1. The inp_buffer and out_buffer addresses are passed to 
the processing function. 


11) Click Cancel to close this properties dialog without making any changes. 


12) Since the processing function is no longer run within main, what causes 
this SWI object to run its function? In volume.c, the datalO function calls 
SWI_dec, which decrements the mailbox value and posts the software 
interrupt if the new mailbox value is 0. So, this SWI object runs its function 
every tenth time the datalO_CLK object runs the datalO function. 


13) Choose File-Close. You are asked whether you want to save your 
changes to volume.cdb. Click Yes. Saving this file also generates 
volumecfg.cmd, volumecfg.s54, and volumecfg.h54. 
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5.4 Viewing Task Execution with the Execution Graph 


While you could test the program by putting a Probe Point within the 
processing function and view graphs of input and output data (as you did in 
the previous chapter), you have already tested the signal processing 
algorithm. At this stage of development, your focus is on making sure the 
tasks can meet their real-time deadlines. 


1) Choose File-Load Program. Select the program you just built, 
volume.out, and click Open. 


2) Choose Debug->Go Main. The program runs to the first statement in the 
main function. 


3) Choose Tools>DSP/BIOS—RTA Control 


Panel. You see several check boxes at the 
IV enable SW logging 


bottom of the Code Composer Studio 
window. [~ enable PRD logging 


MV enable CLK logging 

T~ enable SW accumulators 
T” enable PRD accumulators 
T” enable PIP accumulators 
Tenable HW accumulators 
T enable USERO trace 

T” enable USER1 trace 


4) Right-click on the area that contains the 
check boxes and deselect Allow Docking, 
or select Float in Main Window, to display 
the RTA Control Panel in a separate 
window. Resize the window so that you 
can see all of the check boxes shown here. 


5) Put check marks in the boxes shown here 
to enable SWI and CLK logging and to 
globally enable tracing on the host. 


6) Choose Tools>DSP/BIOS-—Execution Graph. The Execution Graph 
appears at the bottom of the Code Composer Studio window. You may 
want to resize this area or display it as a separate window. 


IY) clotal target enable 
IV global host enable 


7) Right-click on the RTA Control Panel and choose Property Page from the 
pop-up menu. 


8) Verify that the Refresh Rate for Message Log/Execution Graph is 1 
second and click OK. 


Viewing Task Execution with the Execution Graph 


9) Choose Debug—Run or click the s (Run) toolbar button. The Execution 
Graph should look similar to this: 


waiting 


processing_S'w!l 

Other Threads SS eS es ee 0 teady 
PRD Ticks rr © unknown 
Time B® enor 
Assertions @ tunning 


10 time marks 


10) The marks in the Time row show each time the Clock Manager ran the 
CLK functions. Count the marks between times the processing_SWI 
object was running. There should be 10 marks. This indicates that the 
processing _SWI object ran its function every tenth time the datalO_CLK 
object ran its function. This is as expected because the mailbox value that 
is decremented by the datalO function starts at 10. 
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Changing and Viewing the Load 


Using the Execution Graph, you saw that the program meets its real-time 
deadlines. However, the signal processing functions in a typical program must 
perform more complex and cycle consuming tasks than multiplying a value 
and copying it to another buffer. You can simulate such complex tasks by 
increasing the cycles consumed by the load function. 


‘Note: Load Values in This Example 


The following load values are for a ’C549 running at 100 MIPS. If your ’C54x 
is running at a different soeed you need to multiply the load values by (Your 
MIPS / 100). If you do not know what MIPS you are running at, open 
volume.cdb and look at the Global Settings property called DSP MIPS 
(CLKOUT). 


1) Choose Tools>DSP/BIOS—CPU Load Graph. A blank CPU Load Graph 
appears. 


2) Right-click on the RTA Control Panel and choose Property Page from the 
pop-up menu. 

3) Change the Refresh Rate for Statistics View/CPU Load Graph to 0.5 
seconds and click OK. Notice that the CPU load is currently very low. 


The Statistics View and the CPU Load transfer very little data from the 
target to the host, so you can set these windows to update frequently 
without causing a large effect on program execution. The Message Log 
and Execution Graph transfer the number of words specified for the 
buflen property of the corresponding LOG object in the configuration file. 
Since more data is transferred, you may want to make these windows 
update less frequently. 


4) Choose File>Load GEL. In the Load GEL File dialog, select the 
volume.gel file and click Open. 


5) Choose GEL—Application Control>Load. 


6) Type 3000 as the new load and epee 
click Execute. The CPU load MBmeRSsERREICio 
increases to about 7%. 


Last: 8.81% +0.0 | Peak: 8.83% 


Changing and Viewing the Load 


7) Right-click on the Execution Graph and choose Clear from the pop-up 
menu. Notice that the program still meets its real-time deadline. There are 
10 time marks between each execution of the processing_SWI function. 


8) Using the GEL control, change the load to 5000 and click Execute. 


9) Right-click on the Execution Graph and choose Clear from the pop-up 
menu. One of the time marks occurs while the processing_SWI function 
is executing. Does this mean the program is missing its real-time 
deadline? No, it shows that the program is functioning correctly. The 
hardware interrupt that runs the CLK object functions can interrupt the 
software interrupt processing, and the software interrupt still completes 
its task before it needs to run again. 


processing_SW'l 
Other Threads ee 
PRD Ticks sh 
Ti ime otttttttt 


Assettions 


10) Using the GEL control, change 
the load to 30000 and click 
Execute. The CPU load 
increases to about 95%. 


CPU Load Graph x] 


11) Right-click on the Execution 
Graph and choose Clear from 
the pop-up menu. The program 
still meets its real-time deadline Last: 95.33% +0.0 | Peak: 95.37% 
because processing_SWI 
completes before 10 time 
marks have occurred. 


processing_S'w'l 

SN ee eee ee 
PRD Ticks i 
Time 


Assertions 
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12) Using the GEL control, change the load to 35000 and click Execute. The 
CPU Load Graph and the Execution Graph stop updating as frequently 
and may not update at all. This is because these updates are performed 
within an idle task, which has the lowest execution priority within the 
program. Because the higher-priority threads are using all the processing 
time, there is not enough time for the host control updates to be 
performed. The program is now missing its real-time deadline. 


13) Choose Debug—Halt. This stops the program and updates the Execution 
Graph. The Assertions row in the graph shows errors when the 
application missed a real-time deadline. 


14) Using the GEL control, change | = 
the load to 10 and click Execute. MBaSREsEnAEIe/a zd 
The CPU load and Execution 100% 
Graph begin updating again. 75% 


Last: 2.07% +0.0 | Peak: 99.85% 


‘Note: Modifying the Load Using RTDX 


Using the Load GEL control temporarily halts the target. If you are 
analyzing a real-time system and do not want to affect system performance, 
modify the load using a Real-Time Data Exchange (RTDX) application. The 


next chapter shows how to modify the load in real-time using RTDX. 
L 
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5.6 Analyzing Task Statistics 
You can use other DSP/BIOS controls to examine the load on the DSP and 
the processing statistics for the processing_SWI object. 


1) Choose Tools-+DSP/BIOS-—Statistics View. A Statistics View area that 
says Load DSP/BIOS program and/or set property to use control 
appears. It says this because you need to select the statistics you want 
to view. 


2) Right-click on the Statistics View area and choose Property Page from 
the pop-up menu. Highlight the items shown here and click OK. 


STS Control Properties Eg 


General 


STS Objects: Statistics: 


ocessing_ S\W Count 


IDL_busyObj Total 


Hold down Ctrl key and select list items 


3) You see the statistics fields for the processing SWI objects. You may 
want to make this area a separate window (by right-clicking on it and 
deselecting Allow Docking in the pop-up menu) and resize the window so 
that you can see all four fields. 


Count Total Max Average 


processing_Sw'l J J I 


4) In the RTA Control Panel, put a check mark in the enable SWI 
accumulators box. 
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If you have halted the program, click the *& (Run) toolbar button. 


Notice the Max value in the Statistics View. SWI statistics are measured 
in instruction cycles. 


Using the GEL control, increase the load and click Execute. Notice the 
change in the Max value for the number of instructions performed from 
the beginning to the end of processing_SWI increases. 


Experiment with different load values. If you decrease the load, right-click 
on the Statistics View and select Clear from the pop-up menu. 


This resets the fields to their lowest possible values, allowing you to see 
the current number of instruction cycles in the Max field. 


Click the & (Halt) toolbar button and close all the DSP/BIOS and GEL 
controls you have opened. 


Adding Explicit STS Instrumentation 


5.7 Adding Explicit STS Instrumentation 


In the previous section, you used the Statistics View to see the number of 
instructions performed during a software interrupt’s execution. If you use a 
configuration file, DSP/BIOS supports such statistics automatically. This is 
called implicit instrumentation. You can also use API calls to gather other 
statistics. This is called explicit instrumentation. 


In the Project View, double-click on the volume.cdb file (in the DSP/BIOS 
Config folder) to open it. 


Right-click on the STS manager and choose Insert STS from the pop-up 
menu. 


Rename the new STSO object to processingLoad_STS. The default 
properties for this object are all correct. 


Choose File-Close. You are asked whether you want to save your 
changes to volume.cdb. Click Yes. 


In the Project View, double-click on the volume.c program to open it for 
editing. Make the following changes to the program: 


Add the following lines below the line that includes the swi.h file: 


#include <clk.h> 
#include <sts.h> 
#include <trc.h> 


Add the following to the declarations in the section labeled with the 
comment “objects created by the Configuration Tool”: 


extern STS_Obj processingLoad_STS; 


Add the following lines within the processing function before the call 
to the load function: 


/* enable instrumentation only if TRC_USERO is set */ 
if (TRC_query(TRC_USERO) == 0) { 
STS_set (&processingLoad_STS, CLK_gethtime()); 


} 


Add the following lines within the processing function after the call to 
the load function: 


if (TRC_query(TRC_USERO) == 0) { 
STS_delta(&processingLoad_STS, CLK_gethtime())j; 


} 


Choose File-Save to save your changes to volume.c. 
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5.8 Viewing Explicit Instrumentation 


To view the information provided by the explicit instrumentation calls you 
added, you use the Statistics View and the RTA Control Panel. 


1) Choose File-+Load Program. Select the program you just rebuilt, 
volume.out, and click Open. 


2) Choose Tools-+DSP/BIOS—RTA Control 


Panel. 
Tenable SW logging 
3) Right-click on the RTA Control Panel area [~ enable PRD logging 


and deselect Allow Docking to display the =~ cysble CLK logging 
RTA Control Panel in a separate window. 
Resize the window so that you can see all 
of the check boxes shown here. 


MV enable SWI accumulators 
T enable PRD accumulators 
Tenable PIP accumulators 
4) Put check marks in the boxes shown here’ [~ enable Hw accumulators 
to enable SWI accumulators, USERO | enable USERO trace 
trace, and to globally enable tracing onthe [~ enable USER trace 
host. 


J¥) clobal|taraet enable 
Enabling USERO tracing causes the calls [¥ global host enable 
to TRC_query(TRC_USER0O) to return 0. 


5) Choose Tools>DSP/BIOS-—Stiatistics View. 


6) Right-click on the Statistics View area and choose Property Page from 
the pop-up menu. Highlight the processing SWI and 
processingLoad_STS objects. Also, highlight all four statistics. 


7) Click OK. You see the statistics fields for both objects. You may want to 
make this area a separate window (by deselecting Allow Docking in the 
pop-up menu) and resize the window so that you can see all the fields. 


8) Choose Debug—Run or click the *& (Run) toolbar button. 


Statistics View 


— Total = Average 


processingLoad_STS | J 18490 | I 63.32 
processing Swi | J 440534 inst J vais inst J 1508.68 inst 


IMS 6Hulssedoid 


Viewing Explicit Instrumentation 


9) Subtract the processing SWI Max value from the processingLoad_STS 
Max value. The result should be about 1445 instructions. (The actual 
numbers shown may vary.) SWI statistics are measured in instruction 
cycles. Because you used the CLK_gethtime function to benchmark the 
processing load, processingLoad_STS is in on-chip timer counter 
increments, which are equivalent to instruction cycles. These instructions 
are performed within the processing function, but not between the calls to 
STS_set and STS_delta, as shown below. 


fe  sssS=55= processing ======== */- 
Int processing(Int *input, Int *output) 


{ 


Int size = BUFSIZE; 
while (size-——) { 
*Xoutputt+ = *inputt+ * gain; 


3 } 

S /* enable instrumentation if TRC_USERO is set */ 

8 if (TRC_query(TRC_USERO) == 0) { 

o. STS_set (&processingLoad_STS, CLK_gethtime()); 
= } 

— /* additional processing load */ 

S load (processingLoad) ; 

i if (TRC_query(TRC_USERO) == 0) { 

ja STS_delta(&processingLoad_STS, CLK_gethtime()); 
oO } 


return (TRUE); 


} 


For example, when the load is 10, the processingLoad_STS Max is about 
203 and the processing_SWI Max is about 1648. To calculate the 
instruction cycles performed within the processing function but outside 
the calls to STS_set and STS _delta, the equation is: 


1648 - 203 = 1445 


10) Choose GEL-—Application Control-Load. (If you have closed and 
restarted Code Composer Studio, you must reload the GEL file.) 


11) Change the Load and click Execute. 


12) Notice that while both Max values increase, the difference between the 
two Max values stays the same. 


13) Remove the check mark from the enable USERO trace box in the RTA 
Control Panel. 


14) Right-click on the Statistics View and choose Clear from the pop-up 
menu. 
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15) Notice that no values are updated for processingLoad_STS. This is 
because disabling the USERO trace causes the following statement in the 
program to be false: 


if (TRC_query(TRC_USERO) == 0) 


As a result, the calls to STS_set and STS_delta are not performed. 


16) Before proceeding to the next chapter (after completing section 5.9, page 
5-20), perform the following steps to prepare for the next chapter: 


M@ Click & (Halt) or press Shift F5 to stop the program. 


M Close all GEL dialog boxes, DSP/BIOS plug-ins, and source 
windows. 


5.9 Things to Try 


To further explore DSP/BIOS, try the following: 


1 Change the Statistics Units property of the SWI Manager in the 
configuration file to milliseconds or microseconds. Rebuild and reload the 
program and notice how the values in the Statistics View change. 


1) Modify volume.c by using the CLK_getltime function instead of the 
CLK_gethtime function. Rebuild the program and notice how the values 
in the Statistics View change. The CLK_getltime function gets a 
low-resolution time that corresponds to the timer marks you saw in the 
Execution Graph. You must increase the load significantly to change the 
Statistics View values when using CLK_getitime. 


5.10 Learning More 


To learn more about the CLK, SWI, STS, and TRC modules, see the online 
help or the TMS320C54x DSP/BIOS User's Guide (which is provided as an 
Adobe Acrobat file). 


Chapter 6 


Analyzing Real-Time Behavior 


This chapter introduces techniques for analyzing and correcting real-time 
program behavior. 


In this chapter, you analyze real-time behavior and correct scheduling 
problems using the example from Chapter 5. You use RTDX (Real-Time Data 
Exchange) to make real-time changes to the target, use DSP/BIOS periodic 
functions, and set software interrupt priorities. 


This chapter requires a physical board and cannot be carried out using a 
software simulator. Also, this chapter requires the DSP/BIOS and RTDX 
components of Code Composer Studio. 
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Opening and Examining the Project 


6.1 Opening and Examining the Project 


In this chapter, you modify the example you worked on in the previous 
chapter. 


‘Note: Copy Example Files if Previous Chapter Not Completed 


If you did not complete the previous chapter, you can copy example files 
from the volume? folder that reflect the state of the example at the end of 
the previous chapter. Copy all the files from c:\ti\c5400\tutorial\volume3 (or 
the location where you installed Code Composer Studio) to your working 
folder. 


1) Copy only the following files from the c:\ti\c5400\tutorial\volume4\ folder 
to your working folder. (Note that you should not copy all the files from the 
volumeé4 folder. In particular, do not copy the volume.cdb file.) 


M@ volume.c. The source code has been modified to allow you to use 
the RTDX module to change the load without stopping the target 
program. You examine the changes in section 6.3, page 6-5. 


Mm loadctrl.exe. This is a simple Windows application written in Visual 
Basic 5.0. It sends load values to the target in real time using RTDX. 


@ loadctrl.frm, loadctrl.frx, loadctrl.vbp. If you have Visual Basic, 
you can use it to examine these source files for the loadctrl.exe 
application. 


2) From the Windows Start menu, choose Programs—>Code Composer 
Studio ’C5400—-CCStudio. 


3) Choose Project>Open. Select the volume.mak file in your working folder 
and click Open. 
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6.2 Modifying the Configuration File 


For this example, you need to add one new object to the configuration file. 
(The volume.cdb file in the c:\ti\c5400\tutorial\volume4\ folder already 
contains this object.) 


1) 
2) 


In the Project View, double-click on the volume.cdb file to open it. 


Select LOG_system, change the buflen property to 512 words, and click 
OK (as you did in section 5.3, page 5-6). 


Right-click on the PRD manager and choose Insert PRD from the pop-up 
menu. 


Rename the PRDO object to loadchange_PRD. 


Right-click on the loadchange_PRD object and choose Properties from 
the pop-up menu. 


Set the following properties for the loadchange_PRD object and click OK. 


loadchange_PRD Properties |X! 
Generel 


commert: [<add comments here> 
feroc [tcks): 20 
mode: [continuous | 
tunstion [ozdchange 
=rqJ: jo 
érgl: op 


Fenoc inst 


Change 
these 
properties 


M Change the period to 2. By default, the PRD manager uses the CLK 
manager to drive PRD execution. The default properties for the CLK 
class make a clock interrupt trigger a PRD tick each millisecond. So, 
this PRD object runs its function every 2 milliseconds. 


M@ Change the function to _loadchange. This PRD object executes the 
loadchange C function each time the period you chose elapses. 
(Recall that you need to use an underscore prefix for C functions in 
the configuration file.) You look at this function in the next section. 
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7) 


Click the + sign next to the SWI manager. A SWI object called PRD_swi 
was added automatically. This software interrupt executes periodic 
functions at run time. Therefore, all PRD functions are called within the 
context of a software interrupt and can yield to hardware interrupts. In 
contrast, CLK functions run in the context of a hardware interrupt. 


Click the + sign next to the CLK manager. Notice that the CLK object 
called PRD_clock runs a function called PRD_F_tick. This function 
causes the DSP/BIOS system clock to tick (by calling the PRD_tick API 
function) and the PRD_swi software interrupt to be posted if any PRD 
functions need to run. PRD_swi runs the functions for all the PRD objects 
whose period has elapsed. 


Right click on the PRD manager, and choose Properties from the pop-up 
menu. The PRD manager has a property called Use CLK Manager to 
drive PRD. Make sure this box is checked for this example. 


In your own projects, if you remove the check mark from this box, the 
PRD_clock object would be deleted automatically. Your program could 
then call PRD_tick from some other event, such as a hardware interrupt, 
to drive periodic functions. 


10) Recall that the processing_SWI object has a mailbox value of 10 and that 


14 


12 


the mailbox value is decremented by the datalO_CLK object, which runs 
every millisecond. As a result, the processing_SWI runs its function every 
10 milliseconds. In contrast, the loadchange_PRD object should run its 
function every 2 milliseconds. 


) Choose File->Close. You are asked whether you want to save your 
changes to volume.cdb. Click Yes. Saving this file also generates 
volumecfg.cmd, volumecfg.s54, and volumecfg.h54. 


) Choose Project—Rebuild All or click the (Rebuild All) toolbar button. 


Reviewing the Source Code Changes 


6.3 Reviewing the Source Code Changes 


UNCTIO 


Double-click on the volume.c file in the Project View to see the source code 
in the right half of the Code Composer Studio window. 


Since you copied the volume.c file from the c:\ti\c5400\tutorial\volume4\ folder 
to your working folder, the source code now contains the following differences 
from the source code used in the previous chapter: 


[1 Added the following to the list of included header files: 


#include <rtdx.h> 


1) Added the following to the declarations: 


RTDX_CreateInputChannel (control_channel) ; 
Void loadchange (Void) ; 


1 Added the following call to the main function: 


RTDX_enableInput (&control_channel) ; 


LY The following function is called by the PRD object you created in section 
6.2, page 6-3. This is where the processor is controlled. 


= loadchange ======== 
N: Called from loadchange_PRD to 
cally update load value. 


ARAMET 


ERS: none. 


FF 

* periodi 
BP 
R 


*7 
Void loadc 
{ 


static 


/* Rea 


VALUE: none. 


hange () 
Int control = MINCONTROL; 


d new load control when host sends it */ 


if (!RTDX_channelBusy(&control_channel)) { 


RT 
alte 


} 
el 


DX_readNB(&control_channel, &control, 
sizeof (control)); 
((control < MINCONTROL) || (control > MAXCONTROL)) { 
LOG_printf(&trace,"Control value out of range"); 


se { 
processingLoad = BASELOAD << control; 
LOG_printf(&trace,"Load value = %u",processingLoad) ; 
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This function uses RTDX API functions to change the load of the processing 
signal in real time. Notice the following aspects of these changes: 


Li The call to RTDX_enablelnput enables the input channel called 


control_channel so that data can flow on it from the host to the target. At 
run time, a Visual Basic host client writes a load control value on that 
channel, thereby sending it to the target application. 


The call to RTDX_readNB asks the host to send a load control value on 
the control_channel and stores it in the variable called control. This call is 
non-blocking; it returns without waiting for the host to send the data. The 
data is delivered when the host client writes to control_ channel. From the 
time of the call to RTDX_readNB until the data is written to the variable 
control, this channel is busy, and no additional requests can be posted on 
this channel (that is, calls to RTDX_readNB do not succeed). During that 
time, the call to RTDX_channelBusy returns TRUE for control_channel. 


The processingLoad = BASELOAD << control; statement shifts the bits 
in BASELOAD (1) to the left by the number of digits specified by the 
control. Because MAXCONTROL is set to 31, the RTDX control allows 
you to set an exponentially scaled value for the load up to the maximum 
value that can be stored in a 32-bit variable. 


Using the RTDX Control to Change the Load at Run Time 


6.4 Using the RTDX Control to Change the Load at Run Time 


While you could test the program by putting a Probe Point within the 
processing function and view graphs of input and output data (as you did in 
section 4.3, page 4-6), you have already tested the signal processing 
algorithm. At this stage of development, your focus is on making sure the 
tasks you have added can still meet their real-time deadlines. Also, Probe 
Points halt the target and interfere with the real-time aspects of the test. 


Choose File-Load Program. Select the program you just rebuilt, 


volume.out, and click Open. 


Choose Tools-~DSP/BIOS->RTA Control 
Panel. 


Right-click on the RTA Control Panel and 
deselect Allow Docking to display the RTA 
Control Panel in a separate window. 
Resize the window so that you can see all 
of the check boxes shown here. 


Put check marks in the boxes shown here 
to enable SWI, PRD, and CLK logging; 
SWI and PRD accumulators; and global 
tracing on the host. 


Choose Tools >DSP/BIOS-—Execution 
Graph. The Execution Graph area 


RTA Control Panel x! 


Iv 


r 


enable S'w'l logging 
enable PRD logging 
enable CLK logging 
enable S'\wl accumulators 
enable PRD accumulators 
enable PIP accumulators 
enable Hil accumulators 
enable USERO trace 
enable USER] trace 


= 
- 
r 
IF 
IV 


a\Gial target enanle 
global host enable 


appears at the bottom of the Code Composer Studio window. You may 
want to resize this area or display it as a separate window. 


Choose Tools>DSP/BIOS- Statistics View. 
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7) Right-click on the Statistics View area, which says Load program and/or 
set property to use control. Choose Property Page from the pop-up 
menu. Highlight the items shown here. 


Statistics View Properties fed 


General | 


STS Objects: Statistics: 


loadchange PRD Count 
IDL_busyO bj 
processingLoad STS 


8) Click OK. 
9) Resize the Statistics area to see the fields for the statistics you selected. 


10) Right-click on the RTA Control Panel and choose Property Page from the 
pop-up menu. 


11) Set the Refresh Rate for Message Log/Execution Graph to 1 second and 
the Refresh Rate for Statistics View/CPU Load Graph to 0.5 seconds. 
Then click OK. 


12) Choose Tools—RTDX. 


13) Notice that RTDX is already enabled. This happened behind-the-scenes 
in Step 2 when you opened a DSP/BIOS control. DSP/BIOS controls 
configure and enable RTDX in continuous mode. In continuous mode, 
RTDX does not record data received from the target in a log file (as it 
does in non-continuous mode). This allows continuous data flow. (If your 
program does not use DSP/BIOS, you can use the RTDX area to 
configure and enable RTDX directly.) 


Using the RTDX Control to Change the Load at Run Time 


14) Using the Windows Explorer, run loadctrl.exe, which is located in your 
working folder. The Load Control window appears. 


ia. Load Control |. {OE x} 


This simple Windows application was written using Visual Basic and 
RTDX. If you have Visual Basic, you can examine the source files for the 
loadctrl.exe application stored in the c:\ti\c5400\tutorial\volume4\ folder. 
This application uses the following RTDX functions: 


M@ rtdx.Open("control_channel", "W"). Opens a control channel to 
write information to the target when you open the application 


M@ rtdx.Close(). Closes the control channel when you close the 
application 


M@ rtdx.Writel2(datal2, bufstate). Writes the current value of the slider 
control to control_channel so that the target program can read this 
value and use it to update the load 


15) Choose Debug—Run or click the yy (Run) toolbar button. 


processing_Sw'l 
loadchange_PRD 
PRD_swi 

Other Threads 
PRD Ticks 

Time 

Assertions 


Notice that processing _SWI occurs once every 10 time ticks (and PRD 
ticks). PRD_swi runs once every 2 PRD ticks. The loadchange_PRD runs 
within the context of PRD_swi. These are the expected execution 
frequencies. 
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Using the RTDX Control to Change the Load at Run Time 


processing_Swi 
loadchange_PRD 
PRD_swi 

Other Threads 
PRD Ticks 

Time 

Assertions 


PRD statistics are measured in PRD ticks. SWI statistics are measured 
in instruction cycles. The Max and Average fields for loadchange_PRD 
show that there is less than a full PRD tick between the time this function 
needs to start running and its completion. (The actual numbers shown 
may vary.) 


Statisti 


Max Average 


loadchange_PRD | 7523 | O ticks | 0.00 ticks 


processing Swi | 1504 [4767 inst =f 1741.58 inst 
PRD_swi | 7523 | 595 inst j 392.94 inst 


16) Use the Load Control window to gradually increase the processing load. 
(If you move the slider in the Load Control window while the DSP program 
is halted, the new load control values are buffered on the host by RTDX. 
These have no effect until the DSP application runs again and calls 
RTDX_readNB to request updated load values from the host.) 


17) Repeat step 16 until you see the Max and Average values for 
loadchange_PRD increase and blue squares appear in the Assertions 
row of the Execution Graph. Assertions indicate that a thread is not 
meeting its real-time deadline. 


Count Average 


loadchange_PRD | 35654 J er ticks 262.15 ticks 
processing Swi | 7330 J 248495 inst | 141907.02 inst 
PRD_swi | 35654 J 148907 inst | 9012.40 inst 


What is happening? The Max value for loadchange_PRD increases when you 
increase the load beyond a certain point. With the increased load, the 
processing_SWI takes so long to run that the loadchange_PRD cannot begin 
running until long past its real-time deadline. 


When you increase the load so much that the low-priority idle loop is no 
longer executed, the host stops receiving real-time analysis data and the 
DSP/BIOS plug-ins stop updating. Halting the target updates the plug-ins with 
the queued data. 


Modifying Software Interrupt Priorities 


6.5 Modifying Software Interrupt Priorities 


To understand why the program is not meeting its real-time deadline, you 
need to examine the priorities of the software interrupt tasks. 


1) 
2) 
3) 


) 
) 
8) 
) 
0 


Select Debug—Halt to halt the target. 
In the Project View, double-click on the volume.cdb file to open it. 


Highlight the SWI manager. Notice the SWI = Sy Priority 1 (Highest) 
object priorities shown in the right half of the 3 PRD_swi 


window. SBF processing_S'wl 


Because PRD_swi and processing_SWI have 
the same priority, PRD_swi cannot preempt processing_SWI. The 
processing_SWI needs to run once every 10 milliseconds and PRD_swi 
needs to run every 2 milliseconds. When the load is_ high, 
processing_SWI takes longer than 2 milliseconds to run, and so it 
prevents PRD_swi from meeting its real-time deadline. 

To correct this problem, you need give = © Priority 2 (Highest) 
PRD_swi the highest priority. Drag 3 PRD_swi 
processing SWI down. This adds a second | SD Priority 1 

priority level. Now, PRD_swi has the highest 


peak 38 processing_S'wl 
priority. 


Select File+Save to save your changes. 


Select File—Close to close volume.cdb. 


Select File+Reload Program. 


10) Select Debug—Run to run the example again. Use the RTDX-enabled 


Windows application loadctrl.exe to change the load at run time (as in 
section 6.4, page 6-7). 


11) Notice that you can now increase the load without causing PRD_swi to 


miss its real-time deadline. 


Note: Starving Idle Loop 


It is still possible to starve the idle loop by increasing the processing load to 
maximum. 


12) Before proceeding to the next chapter (after completing section 6.6, page 


6-12), perform the following steps to prepare for the next chapter: 
M@ Click & (Halt) or press Shift F5 to stop the program. 
M@ Close all GEL dialog boxes, DSP/BIOS plug-ins, and source 


windows. 
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6.6 Things to Try 


To further explore DSP/BIOS, try the following: 


11 When you increase the load, the Execution Graph shows that 
processing_SWI requires more than one PRD tick to run. Does this mean 
that processing SWI is missing its real-time deadline? Recall that 
processing_SWI must run every 10 milliseconds, while PRD ticks occur 
every millisecond. 


1 What would happen if the processing function were called directly from a 
hardware ISR rather than being deferred to a software interrupt? That 
would cause the program to miss its real-time deadline because 
hardware ISRs run at higher priority than the highest priority SWI object. 
Recall that when the load is high, PRD_swi needs to preempt 
processing_SWI. If processing_SWI is a hardware interrupt, it cannot be 
preempted by PRD_swi. 


1 View the CPU Load Graph. Use the RTA Control Panel to turn the 
statistics accumulators on and off. Notice that the CPU Load Graph 
appears unaffected. This demonstrates that the statistics accumulators 
place a very small load on the processor. 


How much do the statistics accumulators affect the statistics for 
processing_SWI? Watch the statistics view as you turn the statistics 
accumulators on and off. The difference is a precise measurement of the 
number of instructions each accumulator requires. Remember to 
right-click and clear the statistics view to see the effect. 


4 Add calls to STS_set and STS_delta in the loadchange function like the 
ones you added in section 5.7, page 5-17. How does this change affect 
the CPU load? Now, add calls to STS_set and STS_delta in the datalO 
function. How does this change affect the CPU load? Why? Consider the 
frequency at which each function is executed. Even small increases to 
the processing requirements for functions that run frequently can have 
dramatic effects on CPU load. 


6.7 Learning More 


To learn more about the software interrupt priorities and the RTDX and PRD 
modules, see the Code Composer Studio and RTDX online help or the 
TMS320C54x DSP/BIOS User's Guide (which is provided as an Adobe 
Acrobat file). 
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Chapter 7 


Connecting to I/O Devices 


This chapter introduces RTDX and DSP/BIOS techniques for implementing I/O. 


In this chapter, you connect a program to an I/O device using RTDX and 
DSP/BIOS. You also use the HST, PIP, and SWI modules of the DSP/BIOS API. 


This chapter requires a physical board and cannot be carried out using a 
software simulator. Also, this chapter requires the DSP/BIOS and RTDX 
components of Code Composer Studio. 
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Opening and Examining the Project 


7.1 Opening and Examining the Project 
You begin by opening a project with Code Composer Studio and examining 
the source code files and libraries used in that project. 


1) If you installed Code Composer Studio in c:\ti, create a folder called 
hostio in the c:\ti\myprojects folder. (If you installed elsewhere, create a 
folder within the myprojects folder in the location where you installed.) 


2) Copy all files from the c:\ti\c5400\tutorial\\nostio1 folder to this new folder. 


3) From the Windows Start menu, choose Programs-+Code Composer 
Studio ’C5400—-CCStudio. 


4) Choose Project>Open. Select the hostio.mak file in the folder you 
created and click Open. 


5) Expand the Project View by 
clicking the + signs next to 


Project, _HOSTIO.MAK, and + GEL files 
Source. The hostiocfg.cmd file, = Project 
which was created when the F-eg HOSTIO.MAK 
configuration was saved, }-g DSP/BIOS Config 
includes a large number of “s HOSTIO.CDB 
DSP/BIOS header files. You do HOSTIOCFG.CMD 
not need to examine all these +)~(Q Include 
header files. (} Libraries 

: : : =) Source 
The files used in this project HOSTIO.C 
include: HOSTIOCFG.S54 


H@ hostio.c. This is the source 
code for the main program. 
You examine the source 
code in the next section. 


H@  signalprog.exe. This Visual Basic application generates a sine wave 
and displays the input and output signals. 


Mm slider.exe. This Visual Basic application allows you to control the 
volume of the output signal. 


H@ hostiocfg.cmd. This linker command file is created when saving the 
configuration file. The only object that has been added to the default 
configuration is a LOG object called trace. 


H@ hostiocfg.s54. This assembly file is created when saving the 
configuration file. 


M@ hostiocfg.h54. This header file is created when saving the 
configuration file. 
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7.2 Reviewing the C Source Code 


The example in this chapter simulates a DSP application that digitizes an 
audio signal, adjusts its volume, and produces an analog output at the 
adjusted volume. 


For simplicity, no actual device is used to send and receive analog data in this 
example. Instead, the example tests the algorithm using host-generated 
digital data. Input and output data and volume control are transferred 
between the host and the target using RTDX. 


A Visual Basic application running on the host uses RTDX to generate the 
input signal and display the input and output signals. This application allows 
developers to test the algorithm without stopping the target. Similar methods 
can be used to create display controls for real-time testing of other 
applications. You examine the Visual Basic application in section 7.3, page 
7-6. 


1) Double-click on the hostio.c file in the Project View to see the source 
code. 


2) Notice the following aspects of this example: 


M@ Three RTDX channels are declared globally. The first input channel 
controls the volume. The second input channel receives the input 
signal from the host. The output channel sends the output signal from 
the target to the host. (Input and output channels are named from the 
perspective of the target application: input channels receive data 
from the host, and output channels send data to the host.) 


M@ The call to RTDX_channelBusy returns FALSE if the channel is not 
currently waiting for input. This indicates that the data has arrived and 
can be read. As in Chapter 6, the call to RTDX_readNB is 
non-blocking; it returns control to the DSP application without waiting 
to receive the data from the host. The data is delivered 
asynchronously when the host client writes it to the control_channel. 


M Calls to RTDX_Poll are used to communicate with the underlying 
RTDX layer to read and write data. 


H@ The call to RTDX_read waits for data if the channel is enabled. 


m@ The call to RTDX_write writes the contents of the buffer to the output 
RTDX channel if the channel is enabled. 
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include <std.h> 
include <log.h> 
include <rtdx.h> 


include "target.h" 


et 


define BUFSIZE 64 
define MINVOLUME 


1 


typedef Int sample; 


Reviewing the C Source Code 


M@ While control_channel is enabled by the target via a call to 
RTDX_enablelnput, the other RTDX channels are not enabled from 
this program. Instead, a host program described in the next section 
enables these channels. This is because the slider control, which 
uses the control_channel, is viewed as an integral part of the 
application. By enabling this channel in the target program, you know 
the channel is enabled while the application is running. In contrast, 
the A2D and D2A channels are used to test the algorithm. Hence, 
these channels are enabled and disabled by the host application. 


/* representation of a data sample from A2D */ 


/* Global declarations */ 


sample inp_buffer[BUFSIZI 
sample out_buffer[BUFSIZI 


Al Fl 


l; 
l; 


Int volume = MINVOLUME; /* the scaling factor for volume control */ 


/* RTIDX channels */ 


RTDX_CreateInputChannel (control_channel) ; 
RTDX_CreateInputChannel (A2D_channel); 
RTDX_CreateOutputChannel (D2A_channel) ; 


/* Objects created by 
extern LOG_Obj trace; 


the Configuration Tool */ 


/* 
* main 
*/ 
Void main () 
{ 
sample *input = inp_buffer; 
sample *output = out_buffer; 


Uns size = BUFSIZI 


TARGET_INITIALIZE 


LOG_printf (&trace 


Ej 


Qi /* Enable RTDX interrupt */ 


,"hostio example started"); 


/* enable volume control input channel */ 
RTDX_enableInput (&control_channel) ; 
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while (TRUE) { 


/* Read a new volume when the hosts send it */ 
if (!RTDX_channelBusy (&control_channel) ) { 
RTDX_readNB(&control_channel, &volume, sizeof (volume) ); 


} 


while (!RTDX_isInputEnabled(&A2D_channel) ) { 
RTDX_Poll(); /* poll comm channel for input */ 
} 


/* 
* A2D: get digitized input (get signal from the host through 
* RTDX). If A2D_channel is enabled, read data from the host. 
* /; 


RTDX_read(&A2D_channel, input, size*sizeof (sample) ); 


/* 
* Vector Scale: Scale the input signal by the volume factor to 
* produce the output signal. 
af 

while (size-—) { 

*xoutputt+ = *inputt+ * volume; 

} 

size = BUFSIZE; 

input = inp_buffer; 

output = out_buffer; 


/* 
* D2A: produce analog output (send signal to the host through 
* RTDX). If D2A_ channel is enabled, write data to the host. 
x7 


RTDX_write(&D2A_channel, output, size*sizeof (sample) ); 
while (RTDX_writing) { 


RTDX_Poll(); /* poll comm channel for output */ 
} 
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7.3 
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Reviewing the Signalprog Application 


The source code for the Visual Basic signalprog.exe application is available 
in the signalfrm.frm file. Details about this application are provided in the 
signalprog.pdf Adobe Acrobat file. In this section, you examine a few of the 
routines and functions that are important for this example. 


| 


Test_ON. This routine runs when you click the Test_ON button. It creates 
instances of the RTDX exported interface for the input channel (toDSP) 
and for the output channel (fromDsp). Then it opens and enables both of 
these channels. The channels in the signalprog.exe application are the 
same channels declared globally in the hostio.c source code. 


This routine also clears the graphs and starts the timer used to call the 
Transmit_Signal and Receive_Signal functions. 


These global declarations made earlier in the Visual Basic source code 
connected the READ _CHANNEL and WRITE_CHANNEL used in the 
Test_ON routine to the D2A_channel and A2D_channel used in hostio.c: 
" Channel name constants 


Const READ_CHANNEL = "D2A_ channel" 
Const WRITE_CHANNEL = "A2D_channel" 


Test_OFF. This routine disables, closes, and releases the RTDX objects 
created by Test_ON. It also disables the timer. 


Transmit_Signal. This function generates a sine wave signal and 
displays it in the Transmitted Signal graph. Then, the function attempts to 
transmit the signal to the target using the Write method of the toDSP 
channel. 


Receive_signal. This function uses the ReadSAl2 method of the 
fromDSP channel to read a signal from the target. It displays the signal in 
the Received Signal graph. 


tmr_MethodDispatch_Timer. This routine calls the Transmit_Signal and 
Receive_Signal functions. This routine is called at 1 millisecond intervals 
after the timer object is enabled by the Test_ON routine. 


Running the Application 


7.4 Running the Application 


1) 
2) 
3) 

) 


o 
a 


oO 
aS 


eS 


Choose File-Load Program. Select hostio.out and click Open. 
Choose Tools-RTDX. 


Click Configure in the RTDX area of the window. In the General Settings 
tab of the RTDX Properties dialog, select Continuous RTDX mode. Then, 
click OK. 


Change RTDX Disable to RTDX Enable in the RTDX area. This changes 
the Configure button to Diagnostics. 


Choose Tools-+DSP/BIOS—Message Log. Right-click on the Message 
Log area and choose Property Page from the pop-up window. Select 
trace as the name of the log to monitor and click OK. 


Choose Debug—Run or click the yy (Run) toolbar button. 


Using Windows Explorer, run signalprog.exe and slider.exe. You see 
these two Visual Basic applications. 


ey Yolume Slider |. | x) | 


eeecescessenssessscseseescenseonscsscosscessecesoosssensosssocecesssescenssonscasssossoessecsecesseessonssececoessessonsecssscsscosscesseonscessscssosssocesosessensonssocsosseseseee? 


The slider.exe program must be started after RTDX is enabled and the 
program is running because it creates and opens the RTDX control 
channel when you run the program. If RTDX is not enabled at this point, 
slider.exe cannot open the channel. 
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Running the Application 


The signalprog.exe program can be started at any point. It does not use 
RTDX until you click the Test On button. 


9) Resize the signalprog window so that it is taller. This allows you to see 
the axis labels. 


10) Click Test On in the signalprog window. This starts the input and output 


channels. 
aa signalprog T_ {of x! 
Transmitted Signal Test 


PELICAN AINE 
ATTN NATTA 
HA eh a 


7-8 


Running the Application 


11) Slide the control in the Volume Slider window. This changes the volume 
of the output signal. Watch the amplitude of the Received Signal graph 
change. 


‘Note: Initial Setting of Volume Slider 


The initial setting of the Volume Slider bar is not synchronized with the 


application. They are synchronized the first time you move the slider bar. 
L 


‘Note: Scale of Signal Graphs 


The received signal graph changes the scale to accommodate the size of 


the sine wave. 
L 


12) Close the Volume Slider application. This stops the input and output 
channels. 


13) Click Test OFF in the signalprog window. This closes the control channel. 
14) Click & (Halt) or press Shift F5 to stop the program. 


15) You now see the “hostio example started” message from the call to 
LOG_printf in the Message Log area. You did not see this message 
earlier because the entire program runs within the main function. 
DSP/BIOS communicates with the host PC within the idle loop. Until a 
program returns from main, it never enters the idle loop. Therefore, if you 
want to see the effects of DSP/BIOS calls at run-time, your program 
should perform its functions after returning from main. The modified 
version of hostio.c used in the next section shows this technique. 
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/* =ssss==== A2DscaleD2A 
/* FUNCTION: 


R 
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* 
* 

* PARAMETERS: 
* RETURN VALUE: 


Modifying the Source Code to Use Host Channels and Pipes 


Now you modify the example to use the host channels and pipes provided 
with DSP/BIOS. The modified example still tests your DSP algorithm in real 
time. Rather than generating a sine wave on the host, this time the data 
comes from a host file. 


The HST module provides a more direct path toward implementing I/O with 
peripheral devices. The HST module uses the PIP module for host I/O. You 
can use the PIP module API with minimal modifications to the source code 
once the I/O devices and ISRs are ready for testing. 


1) 


Copy only the following files from the c:\ti\ic5400\tutorial\hostio2\ folder to 
your working folder. (Note that you should nof copy all the files from the 
hostio2 folder. In particular, do not copy the hostio.cdb file.) 


MH hostio.c. The source code has been modified to use the HST and 
PIP modules of the DSP/BIOS API instead of RTDX to transfer the 
input and output signals 


HM input.dat. This file contains input data 


Double-click on the hostio.c file in the Project View to see the source code 
in the right half of the Code Composer Studio window. The source code 
now contains the following differences from the source code used earlier 
in this chapter: 


M@ Added the following to the list of included header files: 


#include <hst.h> 
#include <pip.h> 


mM Removed the BUFSIZE definition, the global declarations of 
inp_buffer and out_buffer, and the RTDX input and output channel 
declarations. This example retains the RTDX channel used to control 
the volume. 


M@ Moved the input and output functionality from a while loop in the main 
function to the A2DscaleD2A function. 


asssss=5 */ 


Called from A2DscaleD2A_SWI to get digitized data 


from a host file through an HST input channel, 
scale the data by the volume factor, and send 


Bis 


output data back to the host through an HST 
output channel. 


Address of input and output HST channels. 


None. 


my, 


Modifying the Source Code to Use Host Channels and Pipes 


Void A2DscaleD2A(HST_Obj *inpChannel, HST_Obj *outChannel) 


{ 


PIP_Obj *inp_PIP; 
PIP_Obj *out_PIP; 
sample *input; 
sample *output; 
Uns size; 


inp_PIP 
out_PIP 


HST_getpipe (inpChannel) ; 
HST_getpipe (outChannel) ; 


if ((PIP_getReaderNumFrames(inp_PIP) <= 0) || 
(PIP_getWriterNumFrames(out_PIP) <= 0)) { 
/* Software interrupt should not have been triggered! */ 
error(); 


/* Read a new volume when the hosts send it */ 
if (!RTDX_channelBusy (&control_channel) ) 
RTDX_readNB(&control_channel, &volume, sizeof (volume) ); 


/* A2D: get digitized input (get signal from the host 
* through HST). Obtain input frame and allocate output 
* frame from the host pipes. */ 


PIP_get (inp_PIP); 
PIP_alloc(out_PIP); 


input = PIP_getReaderAddr (inp_PIP); 
output = PIP_getWriterAddr(out_PIP); 
size = PIP_getReaderSize(inp_PIP); 


/* Vector Scale: Scale the input signal by the volume 
* factor to produce the output signal. */ 
while (size-——) { 
*output++ = *input++ * volume; 


} 


/* D2A: produce analog output (send signal to the host 
* through HST). Send output data to the host pipe and 
* free the frame from the input pipe. */ 

PIP_put (out_PIP); 

PIP_free(inp_PIP); 


The A2DscaleD2A function is called by the A2DscaleD2A_SWI 
object. You create this SWI object in the next section and make it call 
the A2DscaleD2A function. 


The A2DscaleD2A_SWI object passes two HST objects to this 
function. This function then calls HST_getpipe to get the address of 
the internal PIP object used by each HST object. 
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Calls to PIP_getReaderNumFrames and PIP_getWriterNumFrames 
then determine whether there is at least one frame in the input pipe 
that is ready to be read and one frame in the output pipe that can be 
written to. 


Using the same RTDX calls used in section 7.2, page 7-3, the 
function gets the volume setting from the RTDX control channel. 


The call to PIP_get gets a full frame from the input pipe. The call to 
PIP_getReaderAddr gets a pointer to the beginning of the data in the 
input pipe frame and PIP_getReaderSize gets the number of words 
in the input pipe frame. 


The call to PIP_alloc gets an empty frame from the output pipe. The 
call to PIP_getWriterAddr gets a pointer to the location to begin 
writing data to in the output pipe frame. 


The function then multiplies the input signal by the volume and writes 
the results to the frame using the pointer provided by 
PIP_getWriterAddr. 


The call to PIP_put puts the full frame into the output pipe. The call 
to PIP_free recycles the input frame so that it can be reused the next 
time this function runs. 


M@ = Added an error function, which writes an error message to the trace 
log and then puts the program in an infinite loop. This function runs if 
A2DscaleD2A runs when there are no frames of data available for 
processing. 


More about Host Channels and Pipes 


Each host channel uses a pipe internally. When you are using a host channel, 
your target program manages one end of the pipe and the Host Channel 
Control plug-in manages the other end of the pipe. 


When you are ready to modify your program to use peripheral devices other 
than the host PC, you can retain the code that manages the target’s end of 
the pipe and add code in functions that handle device I/O to manage the other 
end of the pipe. 
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Adding Channels and an SWI to the Configuration File 


The A2DscaleD2A function is called by an SWI object and uses two HST 
objects. You create these objects in this section. (The hostio.cdb file in the 
c:\ti\c5400\tutorial\hostio2\ folder already contains these objects.) 


The A2DscaleD2A function also references two PIP objects, but these 
objects are created internally when you create the HST objects. The 
HST_getpipe function gets the address of the internal PIP object that 
corresponds to each HST object. 


1) 
2) 


In the Project View, double-click on the HOSTIO.CDB file to open it. 
Right-click on the HST manager and choose Insert HST. 


Notice that there are HST objects called RTA_fromHost and RTA_toHost. 
These objects are used internally to update the DSP/BIOS controls. 


Rename the new HSTO object to inout_HST. 


Right-click on the input_HST object and choose Properties from the 
pop-up menu. Set the following properties for this object and click OK. 


input_HST Properties | 


General | 
comment: [<add comments here> 
mode: 
bufseg: [ioaTA 
bufalign: ae 


framesize (words): [ea 


Change 


numframes: [2 

these 
T statistics properties 
notify: [_SWI_andn 
argQ: [A2DscaleD 24_ Swi 
ari: 1 


Cancel | Help | 


Apply 
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HM mode. This property determines which end of the pipe the target 


program manages, and which end the Host Channel Control plug-in 
manages. An input channel sends data from the host to the target. 
An output channel sends data from the target to the host. 


framesize. This property sets the size of each frame in the channel. 
Use 64 words—the same value as the BUFSIZE defined in section 
7.2, page 7-3. 


notify, argO, arg1. These properties specify the function to run when 
this input channel contains a full frame of data and the arguments to 
pass to that function. The SWI_andn function provides another way 
to manipulate a SWI object’s mailbox. 


In Chapter 5, you used the SWI_dec function to decrement the 
mailbox value and run the SWI object’s function when the mailbox 
value reached zero. 


The SWI_andn function treats the mailbox value as a bitmask. It 
clears the bits specified by the second argument passed to the 
function. So, when this channel contains a full frame (because the 
target filled a frame), it calls SWl_andn for the A2DscaleD2A_SWI 
object and causes it to clear bit 0 of the mailbox. 


Mailbox value = 3 


PPPP PPP PP PP PPP 


A2DscaleD2A_ Syl 
SWI object 


input HST object 
performs 
S¥VVl_andn with 


Mailbox value = 2 
mask=1 


PPPPPP PP PP PPP Ho 
A2DscaleD2A_ Syl 
SWI abject 
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5) Insert another HST object and rename it output_HST. 
6) Set the following properties for the output_HST object and click OK. 


output_HST Properties 


<add comments here> 


IDATA 


Change 
these 
properties 


S'wi_andn 


AZDscaleD24_ Swi 


When this output channel contains an empty frame (because the target 
read and released a frame), it uses SWI_andn to clear bit 1 of the 
mailbox. 


Mailbox value = 2 
PPP PSP PPP PP Pep He 
A2DscaleD2A_SVvl 


SWI object 


output_HST object 
performs 
SWiI_Landn with Mailbox value = 0 


mesk2 bpppPPPPPPPPEPPE 


A2DscaleD2A_SWI SV is 
SWI object posted 
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7) 
8) 
9) 


Right-click on the SWI manager and choose Insert SWI. 
Rename the new SWIO object to A2DscaleD2A_SWI. 
Set the following properties for A2DscaleD2A_SWI and click OK. 


A2DscaleD2A4_SWI Properties Ei 


General 


comment: [<add comments here> 
priority: fC 
function: [_A2DscaleD24  ¢— 
mailbox: Be 
arg0: finpu HST a 
argl: output HST = €— 


: Cancel | Apply Help | 


M function. This property causes the object to call the A2DscaleD2A 
function when this software interrupt is posted and runs. 


Change 
these 
properties 


H@ mailbox. This is the initial value of the mailbox for this object. The 
input_HST object clears the first bit of the mask and the output_HST 
object clears the second bit of the mask. When this object runs the 
A2DscaleD2A function, the mailbox value is reset to 3. 


M@ arg0, argi. The names of the two HST objects are passed to the 
A2DscaleD2A function. 


10) Choose File-Close. You are asked whether you want to save your 


changes to hostio.cdb. Click Yes. Saving the configuration also generates 
hostiocfg.cmd, hostiocfg.s54, and hostiocfg.h54. 


Running the Modified Program 


7.8 Running the Modified Program 
1) Choose Project—Rebuild All or click the (Rebuild All) toolbar button. 


2) Choose File-+Load Program. Select the program you just rebuilt, 
hostio.out, and click Open. 


3) Choose Tools>DSP/BIOS-—sHost Channel Control. The Host Channel 
Control lists the HST objects and allows you to bind them to files on the 
host PC and to start and stop the channels. 


Hast Channel Control 


Channel Transfert... Mode | Binding i 
input_HST OB OKB Unbound Input = <unbound> 
output_HST OB OKB Unbound Output <unbound> 


4) Choose Debug—Run or click the a (Run) toolbar button. 


5) Right-click on the input_HST channel and choose Bind from the pop-up 
menu. 


6) Select the input.dat file in your working folder and click Bind. 


7) Right-click on the output_HST channel and choose Bind from the pop-up 
menu. 


8) Type output .dat in the File Name box and click Bind. 


input_HST OKB Stopped Input C:\ti\myprojects‘\hostio\input.dat 
output_HST OB OKB Stopped Output C:\timyprojects\hostio\output.dat 


9) Right-click on the inpbut_HST channel and choose Start from the pop-up 
menu. 


10) Right-click on the output_HST channel and choose Start from the pop-up 
menu. Notice that the Transferred column shows that data is being 
transferred. 


11) When the data has been transferred, click & (Halt) or press Shift F5 to 
stop the program. 


7.9 Learning More 
To learn more about the RTDX, HST, PIP, and SWI modules, see the online 


help or the TMS320C54x DSP/BIOS User's Guide (which is provided as an 
Adobe Acrobat file). 
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